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Chapter 1 


Messaging API 


1.1 References 


[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 
[2] Messaging Framework API, Version 1.0, LiMo Foundation, 1 February 2008 


1.2 Overview 


The LiMo Messaging API (MAPI) provides services to send, receive, parse and assemble messages over 
arbitrary message delivery mechanisms such as MMS, SMS, email, and i-mode message. The Messaging 
services consist of common functions and sets of service-specific functions. MAPI provides a collection 
of data structures as well as functions to implement the services. The data structures and functions are 
grouped into modules, as listed below: 


e Message Rending and Reception 
e Storage Management 

e Message Storage 

e Folder Storage 


e Account Storage 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


2 Messaging API 


1.5 Plug-in Extension Point Interface 


None 


1.6 Other Interfaces 


None 


1.7 Other Notes 


The following supplemental material is also available in this document. 


e Overview of the LiMo Messaging MAPI 
e Sample Code for Using the LiMo Messaging API 


e Sequence Charts for the LiMo Messaging API 
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Chapter 2 


Data Structure Index 


2.1 Data Structures 


Here are the data structures with brief descriptions: 


_MSG_ACCOUNT_ID_LIST_S (Represents an account id list) ................. 
_MSG_ACCOUNT_S (Represents an account) ...... o... o... eee eee ees 
_MSG_CONTACT_LIST_S (Represents a contact list ) . ........... o... .... .. 
_MSG_CONTACT_S (Represents a contact) ......... o... e... eee eee eee 
MSG_FILTER_ID_LIST_S (Represents a filter id list) ............ o... a 
MSG_FILTER_LIST_S (Represents a filter list ) ............ o... o... ..... 
_MSG_FILTER_S (Represents a filter ) .......... o... e... +... . . +... +. 
_MSG_FOLDER_ID_LIST_S (Represents a folder id list) ............ o... .... 
_MSG_FOLDER_S (Represents a folder ) ......... o... e... +... . . +... 0. 
_MSG_MESSAGE_ID_LIST_S (Represents a message id list). .......... o... .. 
_MSG_MESSAGE_REQUEST_S (Represents a request that will be sent to messaging frame- 
WOTK DY eii e Sede ga RR ee E A R NR 
_MSG_MESSAGE_S (Represents a Message)... ........... . +... ee 
_MSG_MESSAGE_STATUS_S (Represents a message status). ....... o... o... .. 
_MSG_MESSAGE_TYPE_LIST_S (Represents a message types list) .............. 
_MSG_MESSAGE_TYPE_S (Represents a message type) .... o... o... o... +... . .. 
MSG_QUERY_ID_LIST_S (Represents a query Id list). .................... 
MSG_QUERY_LIST_S (Represents a query list) ....... o... o... o... e... .... 
_MSG_QUERY_S (Represents a query rule ) ....... o... o... .. .... +... ee 
MSG_SORT_RULE_S (Represents a sort rule ) ........... o... .. +... .... 
MSG_SORT_TYPE_LIST_S (Represents a sort type list ) . ........... o... .. 
_MSG_STORAGE_ID_LIST_S (Represents a storage id list) .................. 
_MSG_STORAGE_REGISTRY_S (Represents a storage registry emtIY)............. 
_MSG_STRING_S (Represents a string ) .................. o... 


Data Structure Index 
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Chapter 3 


File Index 


3.1 File List 


Here is a list of all files with brief descriptions: 


ComponentOverview.h (Component Programming Interface Overview Header Template for 

Doxygen) 2 cei deen ee SA SE ar e A 
Msg_Mapi_Account.h (Defines the account structure) ............. 2000-00008 
Msg_Mapi_Contact.h (Defines the contact structure) ............ 00.0000 2 ee 
Msg_Mapi_FilterRule.h (Defines the filter related structures). ........ o... ...... 
Msg_Mapi_Folder.h (Defines the folder related structures) ........ o... ...... .. 
Msg_Mapi_Message.h (Defines the message structure) ...... o... o... e... . . .. 
Msg_Mapi_Message_Request.h (Defines the message request structure ) . ............ 
Msg_Mapi_Message_Status.h (Defines the message status Structure). .............. 
Msg_Mapi_QueryRule.h (Defines the query related structure) ........ o... o... .. 
Msg_Mapi_Session.h (Defines session handling and message sending and receiving related func- 
HONS) A NN 
Msg_Mapi_Storage_Account.h (Defines account related functions) ............... 
Msg_Mapi_Storage_Folder.h (Defines folder related functions in MAPI) ............ 
Msg_Mapi_Storage_Manager.h (Defines storage management functions in MAPI) ....... 
Msg_Mapi_Storage_Message.h (Defines message storage related functions in MAPI)...... 
Msg_Mapi_Storage_Registry.h (Defines the storage registry Structure). ............. 
Msg_Mapi_Types.h (Defines general types ) . . . ...... o... ... .. . e... 0000. 


File Index 
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Chapter 4 


Page Index 


4.1 Related Pages 


Here is a list of all related documentation pages: 


Overview of the LiMo Messaging API .... 


Sample Code for Using the LiMo Messaging API ............ o... o... .....-. 


Sequence Charts for the LiMo Messaging API 


Page Index 
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Chapter 5 


Data Structure Documentation 


5.1 MSG ACCOUNT_ID_LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.1.1 Detailed Description 


Represents an account id list. 


Data Fields 


e intiCount 
e MSG_ACCOUNT_ID_T x accountlds 


5.1.2 Field Documentation 
5.1.2.1 int MSG ACCOUNT ID _LIST_S::iCount 


The count of message ids 


5.1.2.2 MSG ACCOUNT_ID_T« MSG ACCOUNT_ID_LIST_S::accountIds 


The pointer to the account id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 


10 Data Structure Documentation 


5.22 MSG ACCOUNT S Struct Reference 


#include <Msg_Mapi_Account.h> 


5.2.1 Detailed Description 


Represents an account. 


All the fields except for pExData contain common information for an account. The field pExData points 
to the user customized structure. This customized structure should be used by application and message 
storage plugin. 


For the more detailed information of account, please refer to Account. This structure is extendable. Please 
refer to Extendability . 


Data Fields 


MSG_ACCOUNT_ID_T accountld 
MSG_STRING_S accountName 
MSG_MESSAGE_TYPE_S msgType 
MSG_FOLDER_ID_T rootFolderld 
MSG_STORAGE_ID_T storageld 
MSG_STORAGE_ID_T defaultMsgStorageld 
size_textDataSize 


void x pExtData 


5.2.2 Field Documentation 
5.2.2.1 MSG ACCOUNT_ID_T MSG ACCOUNT S::accountId 


Indicates the unique account index. 


5.2.2.2 MSG STRING S MSG ACCOUNT S::accountName 


Indicates the display name for this account. 


5.2.2.3 MSG MESSAGE TYPE_S MSG ACCOUNT _S::msgType 


Indicates the message type of an account, such as SMS, MMS, EMAIL and i-mode message. 


5.2.2.4 MSG FOLDER ID_T MSG ACCOUNT S::rootFolderId 


Indicates the root folder which is assigned to this account. 


5.2.2.5 MSG STORAGE ID_T_MSG_ ACCOUNT _S::storageld 


Indicates the storage id in which this account (metadata and extension data) is stored. 
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5.2.2.6 MSG STORAGE ID_T_MSG_ ACCOUNT _S::defaultMsgStorageld 


Indicates default storage id for the message of this account 


5.2.2.7 size_t MSG ACCOUNT S::extDataSize 


Indicates the size of p] 


ExtData 


5.2.2.8 voids MSG_ACCOUNT_S::pExtData 


Used to add account extension data. For example, the mail box setting of Email account. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Acc 


ount.h 
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5.33 MSG CONTACT LIST_S Struct Reference 


#include <Msg_Mapi_Contact.h> 


5.3.1 Detailed Description 


Represents a contact list. 


Data Fields 


e intiCount 
e MSG_CONTACT_S x pContacts 


5.3.2 Field Documentation 
5.3.2.1 int_MSG_CONTACT_LIST_S::¡Count 


Indicates the number of the contacts in the list. 


5.3.2.2 MSG_CONTACT_S*_MSG_CONTACT_LIST_S::pContacts 


The pointer to the contact list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Contact.h 
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54 MSG CONTACT 5S Struct Reference 


#include <Msg_Mapi_Contact.h> 


5.4.1 Detailed Description 


Represents a contact. 


This structure includes the contact basic information. It can present various contact type such as telephone 
number, email address and so on. 


This structure is extendable. Please refer to Extendability . 


Data Fields 


e MSG_CONTACT_TYPE_T contactType 
e unsigned char x contactVal 

e MSG_STRING_S contactName 

e size_t extDataSize 

e void x pExtData 


5.4.2 Field Documentation 


5.4.2.1 MSG CONTACT_TYPE_T MSG CONTACT _S::contactType 


Indicates contact type. 

Two types are predefined: 

MSG_CONTACT_TYPE_EMAIL is for email address like abc@example.com 
MSG_CONTACT_TYPE_PLMN is for phone number like +10123456789 

5.4.2.2 unsigned char» MSG CONTACT. S::contactVal 

The value of the contact. It should be encoded in ASCII. 

For example, the real phone number or email address. 


5.4.2.3 MSG STRING S_ MSG CONTACT S::contactName 


Indicates the display name of this contact. 


5.4.2.4 size_t MSG CONTACT S::extDataSize 


Indicates the size of the extension data which pExt Data point to. The unit is byte. 


5.4.2.5 voids MSG CONTACT _S::pExtData 


Extension data for contact. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


14 Data Structure Documentation 


Some data that is not covered in the structure can be put here, such as picture data and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Contact.h 
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5.5 MSG FILTER ID LIST S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.5.1 Detailed Description 


Represents a filter id list. 


It is composed of various filter ids. 


Data Fields 


e int iCount 
e MSG_FILTER_ID_T « filterlds 


5.5.2 Field Documentation 
5.5.2.1 int MSG FILTER _ID LIST _S::iCount 


Indicates the number of the filter id in the list. 


5.5.2.2 MSG FILTER _ID_T* MSG_FILTER_ID_LIST_S::filterIds 


Indicates the pointer to the filter id list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_FilterRule.h 
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5.6 _ MSG FILTER LIST_S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.6.1 Detailed Description 


Represents a filter list. 


It is composed of various MSG_FILTER_S. The first filter in the list has the highest priority. Framework 
will check the filter list from the first filter to the last one. Once the message satisfies the filter, framework 
stops checking other filters in the list and returns the autoStore and intercept properties of the 
current filter. 


Data Fields 


e intiCount 
¢ MSG_FILTER_S + filters 


5.6.2 Field Documentation 
5.6.2.1 int MSG FILTER LIST S::iCount 


Indicates the number of the filters in the list. 


5.6.2.2 MSG_FILTER_Sx _MSG_FILTER_LIST_S::filters 


The pointer to the filter list. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_FilterRule.h 
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5.7 _MSG FILTER S Struct Reference 


#include <Msg_Mapi_FilterRule.h> 


5.7.1 Detailed Description 


Represents a filter. 


It represents the basic filter unit. 


Data Fields 


e MSG_FILTER_ID_T filterId 
e MSG_STRING_S filterName 
e bool autoStore 

e bool intercept 

e int valueLength 

e unsigned char * filterValue 


5.7.2 Field Documentation 
5.7.2.1 MSG_FILTER_ID_T_MSG_FILTER,_ S::filterld 


Indicates the filter type. 


The filter Id indicates the filter type. There are some predefined filter ids. Please refer to_MSG_FILTER_- 
ID_E 


5.7.2.2 MSG STRING _S_MSG FILTER S::filterName 


Indicates the display name for the filter. 


5.7.2.3 bool MSG FILTER S::autoStore 


Indicates whether the message should be automatically stored by framework, when it satisfies this filter. 


If it is set t rue, the message will be automatically stored by framework when the message satisfies this 
filter. By default, this message will be saved to Inbox in the default account. 


If it is set false, the message will not be stored by framework. 


5.7.2.4 bool _MSG_FILTER_S::intercept 


Indicates whether the message should be intercepted, when it satisfies this filter. 


When the message satisfies this filter, framework will send the message to this filter associated session, 
then check the intercept: 


If it is set true, the sessions whose priority are lower than this filter associated session will not receive this 
message. 


If it is set false, framework will send the message to all the other sessions that are interested in this message. 
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For details about session priority, please refer to MsgSetPriority. 


5.7.2.5 int MSG_FILTER_S::valueLength 


Indicates the length of the filterValue. 


5.7.2.6 unsigned chars MSG FILTER _S::filter Value 


The value of the filter. 


For example, if the filter Id show that the message should be filtered by message type, the value maybe 
SMS, MMS. 


The documentation for this struct was generated from the following file: 


e Msg _Mapi_FilterRule.h 
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5.8 MSG FOLDER ID LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.8.1 Detailed Description 


Represents a folder id list. 


Data Fields 


e int iCount 
¢ MSG_FOLDER_ID_T x folderlds 


5.8.2 Field Documentation 
5.8.2.1 int MSG FOLDER _ID LIST _S::iCount 


The count of message ids 


5.8.2.2 MSG FOLDER_ID_T+ MSG FOLDER _ID_LIST_S::folderIds 


The pointer to the folder id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.9 MSG FOLDER S Struct Reference 


#include <Msg_Mapi_Folder.h> 


5.9.1 Detailed Description 


Represents a folder. 


For the more detailed information of folder, please refer to Folder . This structure is extendable. Please 
refer to Extendability . 


Data Fields 


MSG_FOLDER_ID_T folderld 
MSG_FOLDER_ID_T parentld 
MSG_STRING_S folderName 
MSG_STORAGE ID_T storageld 
MSG_SORT_TYPE_T sortType 
MSG_FOLDER_TYPE_T folderType 
size_t commExtDataSize 

void x pCommExtData 


5.9.2 Field Documentation 
5.9.2.1 MSG FOLDER _ID_T_ MSG FOLDER S::folderId 


Indicates folder id. 


5.9.2.2 MSG FOLDER _ID_T MSG FOLDER S::parentId 


Indicates parent folder id. 


5.9.2.3 MSG STRING S_ MSG FOLDER S::folderName 


Indicates the folder name. 


5.9.2.4 MSG STORAGE ID_T_ MSG _FOLDER_S::storageId 


Indicates the storage id in which this folder (metadata and extension data) is stored. 


5.9.2.5 MSG SORT_TYPE_T_MSG_ FOLDER _S::sortType 


Indicates the sort type for the children nodes under this folder. 


5.9.2.6 MSG FOLDER _TYPE_T MSG FOLDER S::folderType 


Indicates the folder type which can be Inbox/Outbox... 
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5.9.2.7 size_t MSG FOLDER_S::commExtDataSize 


Indicates the size of pCommExtData 


5.9.2.8 voids MSG _FOLDER_S::pCommExtData 


Used to add extension data for framework storage plugin. 


For example, the extension data can be picture, max dispalying size and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Folder.h 
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5.10 MSG MESSAGE ID_LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.10.1 Detailed Description 


Represents a message id list. 


Data Fields 


e int iCount 
e MSG_MESSAGE_ID_T x msglds 


5.10.2 Field Documentation 
5.10.2.1 int_MSG_MESSAGE_ID LIST _S::iCount 


The count of message ids 


5.10.2.2 MSG MESSAGE ID_T« MSG MESSAGE ID LIST_S::msgIds 


The pointer to the message id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.11 _MSG MESSAGE REQUEST _§S Struct Reference 


#include <Msg_Mapi_Message_Request.h> 


5.11.1 Detailed Description 


Represents a request that will be sent to messaging framework. 


Applications compose a request with this structure and send it to message framework via a connected 
session. This request Id is used to manage the request by framework. 


This structure is extendable. Please refer to Extendability . 


Data Fields 


e MSG_REQUEST_TYPE_T reqType 
e MSG_MESSAGE_TYPE_S msgType 
e MSG_REQUEST_ID_T reqld 

e MSG_MESSAGE S x pMsg 

e size_t extDataSize 

e void x pExtData 


5.11.2 Field Documentation 


5.11.2.1 MSG _REQUEST_TYPE_T MSG MESSAGE REQUEST _§S::reqType 


Indicates the type of request. 
Some predefined types: MSG_REQUEST_TYPE_SEND, MSG_REQUEST_TYPE_SENDSAVE 


5.11.2.2 MSG _MESSAGE_TYPE_S MSG MESSAGE REQUEST_S::msgType 


Indicates the message type. 


Indicates the type of the message such as SMS, MMS, Email etc. 


5.11.2.3 MSG_REQUEST_ID_T MSG MESSAGE REQUEST S::reqId 


Indicates the reqeust Id, the unique Id of the request. 


When applications use MsgSubmitReq to submit a request to framework, this value will be set by frame- 
work and returned to applications. Applications should keep this id to trace the request's status or cancel 
the request later. 


5.11.2.4 MSG_MESSAGE_Sx _MSG_MESSAGE_REQUEST_S::pMsg 


The pointer to message structure. 


When applications submit sending message request, this pointer shall point to the message that should be 
sent. 
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5.11.2.5 size_t MSG MESSAGE REQUEST_S::extDataSize 


Indicates the size of the extension data that pExtData point to. The unit is byte. 


5.11.2.6 void: MSG MESSAGE REQUEST _S::pExtData 


Used to add extension data for transport plugin. 
For example, this field can be used to extend new request for specific service. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message_Request.h 
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5.12 ~MSG MESSAGE S Struct Reference 


#include <Msg_Mapi_Message.h> 


5.12.1 Detailed Description 


Represents a message. 


This structure includes the common information of vaious specific service message, such as SMS, MMS, 
Email and i-mode message. 


This structure is extendable. Please refer to Extendability . 


Data Fields 


MSG_MESSAGE_ID_T msgld 
MSG_FOLDER_ID_T parentId 
MSG_MESSAGE_TYPE_S msgType 
MSG_ACCOUNT_ID_T accountld 
MSG_STORAGE_ID_T storageld 
MSG_STRING_S subject 
MSG_CONTACT_S from 
MSG_CONTACT_LIST_S to 
MSG_STRING_S displaySubject 
MSG_STRING_S displayFrom 
MSG_STRING_S displayTo 
time_t displayTime 


size_t size 

MSG_STATUS_T status 
MSG_STATUS_T deliveryStatus 

bool hasAttachment 

bool hasDrmContent 
MSG_MESSAGE_PRIORITY_T priority 
size_t commExtDataSize 

void x pCommExtData 


size_t extDataSize 
void x pExtData 


5.12.2 Field Documentation 
5.12.2.1 MSG MESSAGE _ID_T_MSG MESSAGE S::msgld 


Indicates the message Id of this message. 


5.12.2.2 MSG_FOLDER_ID_T_MSG MESSAGE S::parentId 


Indicates the parent folder ID. 


The parent is a folder. 
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5.12.2.3 MSG_MESSAGE_TYPE_S MSG MESSAGE S::msgType 


Indicates the message type. 


Indicates the type of the message such as SMS, MMS, Email, i-mode etc. 


5.12.2.4 MSG _ACCOUNT_ID_T _MSG_MESSAGE_S::accountld 


Indicates which account the message associated. 


5.12.2.5 MSG STORAGE _ID_T_MSG MESSAGE S::storageld 


Indicates where this message (metadata and extension data) is stored. 


If it is set MSG _STORAGE_DEFAULT, the message will be saved according to 
defaultMsgStorageld in its associated account.Otherwise, the message will be saved accord- 
ing this value. 


5.12.2.6 MSG _STRING_S _MSG_MESSAGE S::subject 


Indicates the subject of the message. 


5.12.2.7 MSG_CONTACT_S_MSG_MESSAGE,_S::from 


Indicates where the message comes from. 


5.12.2.8 MSG _CONTACT_LIST_S MSG_MESSAGE S::to 


Indicates where the message will send to. 


5.12.2.9 MSG _STRING_S MSG MESSAGE S::displaySubject 


Indicates the display content for subject. 


5.12.2.10 MSG STRING_S_MSG_MESSAGE S::displayFrom 


Indicates the display content for from. 


5.12.2.11 MSG STRING_S_MSG_MESSAGE S::displayTo 


Indicates the display content for to. 


5.12.2.12 time t MSG MESSAGE S::displayTime 


Indicates the display content for time. 


For example, if the message is an incoming message, this value should be the time when the message 
arrived. Framework is responsible to set this value in this case. 
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If the message is an outgoing message, this value should be the time when the message be sent out. Appli- 
cation is responsible to set this value in this case. 


5.12.2.13 size_t_ MSG MESSAGE S::size 


Indicates the size of the message. The unit is byte. 


5.12.2.14 MSG STATUS_T _MSG_MESSAGE S::status 


Indicates the message’s local status, such as read/unread/replied/forwarded/protected ... 


5.12.2.15 MSG STATUS_T MSG MESSAGE S::deliveryStatus 


Indicates the delivery status of the message. 


5.12.2.16 bool MSG MESSAGE S::hasAttachment 


Indicates whether the message has attachment. 
If the message has attachment, it should be set t rue. 
If the message does not have attachment, it should be set false. 


5.12.2.17 bool MSG MESSAGE S::hasDrmContent 


Indicates whether the message attaches the DRM contents. 
If it is set t rue, the message attaches the DRM contents. 


If it is set false, the message does not attaches the DRM contents. 


5.12.2.18 MSG MESSAGE PRIORITY_T_ MSG MESSAGE S::priority 


Indicates the priority of this message. 


5.12.2.19 size t_ MSG MESSAGE S::commExtDataSize 


Indicates the size of the data that pCommExtData point to. The unit is byte. 


5.12.2.20 voids MSG MESSAGE S::pCommExtData 


Used to add extension data for framework storage plugin. 


This field is the extension data for framework storage plugin. For example, whether the message is replied 
can be regarded as an common extension attribute. 


5.12.2.21 size_t MSG MESSAGE S::extDataSize 


Indicates the size of the data that pExt Data point to. The unit is byte. 
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5.12.2.22 void: MSG MESSAGE S::pExtData 


Used to add extension data for message storage/transport plugin. 


This field is the extension data for storage/transport plugin. It is the place to put such message payload 
information as body and so on. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message.h 
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5.13 MSG MESSAGE STATUS S Struct Reference 


#include <Msg_Mapi_Message_Status.h> 


5.13.1 Detailed Description 


Represents a message status. 


This stucture contains the information about the status of the request that application has submitted to 
framework. 


This structure is extendable. Please refer to Extendability . 


Data Fields 


MSG_REQUEST_ID_T reqId 
MSG_ERROR_T error 
MSG_STATUS_T status 

bool isFinal 
MSG_MESSAGE_ID_T msgld 
size_textDataSize 


void x pExtData 


5.13.2 Field Documentation 
5.13.2.1 MSG_REQUEST_ID_T_MSG_MESSAGE_STATUS_S::reqld 


Indicates the corresponding request Id. 


5.13.2.2 MSG_ERROR_T_MSG_MESSAGE_STATUS_S::error 


Indicates the error code. 


5.13.2.3 MSG_STATUS_T _MSG_MESSAGE_STATUS_S::status 


Indicates the status of the corresponding request. 


5.13.2.4 bool _MSG_MESSAGE_STATUS_S::isFinal 


Indicates the request is finished or not. If the request is finished, no more status of this request will be sent 
to client and the request information will be removed from messaging framework. 


5.13.2.5 MSG_MESSAGE_ID_T _MSG_MESSAGE_STATUS_S::msgld 


Indicates the saved message id, it’s applicable when status is MSG_STATUS_SAVED_NOTSENT or 
MSG_STATUS_SENT_SAVED. 
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5.13.2.6 size_t MSG MESSAGE STATUS S::extDataSize 


Indicates the size of the extension data that pExtData point to. The unit is byte. 


5.13.2.7 void: MSG MESSAGE STATUS_S::pExtData 


Used to add extension data for transport plugin. 
For example, this field can be used to extend new status for specific service. 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Message_Status.h 
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5.14 MSG MESSAGE TYPE _LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.14.1 Detailed Description 


Represents a message types list. 


Data Fields 


e int iCount 
e MSG_MESSAGE_TYPE_S * pMsgTypes 


5.14.2 Field Documentation 
5.14.2.1 int MSG MESSAGE TYPE_LIST_S::iCount 


The count of message types 


5.14.2.2 MSG_MESSAGE_TYPE_S« MSG MESSAGE_TYPE_LIST_S::pMsgTypes 


The pointer to message types list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.15 ~MSG MESSAGE TYPE S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.15.1 Detailed Description 


Represents a message type. 


This structure includes main type and sub type. 


Data Fields 


e MSG_MAIN_TYPE_T mainType 
e MSG_SUB_TYPE_T subType 


5.15.2 Field Documentation 


5.15.2.1 MSG MAIN TYPE_T MSG MESSAGE _TYPE_S::mainType 


Message main type 


5.15.2.2 MSG SUB_TYPE_T MSG MESSAGE TYPE _S::subType 


Message sub type 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.16 _MSG_ QUERY_ID_LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.16.1 Detailed Description 


Represents a query Id list. 


Data Fields 


e int iCount 
e MSG_QUERY_ID_T * querylds 


5.16.2 Field Documentation 
5.16.2.1 int MSG QUERY _ID LIST_S::iCount 


Indciates the count of the query Id in the list 


5.16.2.2 MSG _QUERY_ID_T*« MSG _QUERY_ID_LIST_S::querylIds 


Indicates the pointer to the query Id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.17 _MSG QUERY_LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.17.1 Detailed Description 


Represents a query list. 


Data Fields 


e intiCount 
e MSG_QUERY_S + queries 


5.17.2 Field Documentation 
5.17.2.1 int MSG QUERY _LIST_S::iCount 


Indciates the count of the query rules in the list 


5.17.2.2 MSG _QUERY_S* MSG _QUERY_LIST_S::queries 


Indicates the pointer to the query list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.18 _MSG QUERY _S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.18.1 Detailed Description 


Represents a query rule. 


When applications need to query all SMS with subject containing some values, a MSG_QUERY_ID_T can 
be added as "MSG_QUERY_SMS_SUBJECT_CONTAIN". 


Refer to the following code: 


MSG_QUERY_S queryRulel; 

queryRule.queryId = MSG_QUERY_BY_ SUBJECT; 
queryRule.queryValue = "SearchingValue"; 
queryRule.valueLength = strlen(queryRule.queryValue) ; 


Data Fields 


e MSG_QUERY_ID_T queryld 
e int valueLength 
e unsigned char * query Value 


5.18.2 Field Documentation 
5.18.2.1 MSG QUERY_ID_T MSG QUERY _S::queryld 


Indicates what kind of rules should be taken when framework filters the messages 


5.18.2.2 int_MSG QUERY S::valueLength 


Indicates the length of the query Value 


5.18.2.3 unsigned chars _MSG_QUERY_S::query Value 


Indicates the value of the query 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.19 MSG SORT_RULE S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.19.1 Detailed Description 


Represents a sort rule. 


The sort rule structure includes sort type and sort order (ascending or descending). Applications can use 
the sort rule when querying messages. 


Data Fields 


e MSG_SORT_TYPE_T sortType 
e bool isAscending 


5.19.2 Field Documentation 


5.19.2.1 MSG _SORT_TYPE_T MSG SORT_RULE_S::sortType 


Indicates the sort type 


5.19.2.2 bool MSG _SORT_RULE_S::isAscending 


Indicates the sort order: ascending or descending 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_QueryRule.h 
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5.20 ~MSG SORT TYPE _LIST_S Struct Reference 


#include <Msg_Mapi_QueryRule.h> 


5.20.1 Detailed Description 


Represents a sort type list. 


Data Fields 


e int iCount 
e MSG_SORT_TYPE_T x sortTypes 


5.20.2 Field Documentation 


5.20.2.1 int _ MSG _SORT_TYPE_LIST_S::iCount 


Indciates the count of the sort type in the list 


5.20.2.2 MSG_SORT_TYPE_T« MSG_SORT_TYPE_LIST_S::sortTypes 


Indicates the pointer to the sort type list 


The documentation for this struct was generated from the following file: 


e Msg _Mapi_QueryRule.h 
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5.21 MSG STORAGE ID _LIST_S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.21.1 Detailed Description 


Represents a storage id list. 


Data Fields 


e int iCount 
e MSG_STORAGE_ID_T x pStoragelds 


5.21.2 Field Documentation 
5.21.2.1 int_MSG_STORAGE_ ID LIST_S::iCount 


The count of storage ids 


5.21.2.2 MSG STORAGE ID_T*« MSG STORAGE ID _LIST_S::pStoragelds 


The pointer to storage id list 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 
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5.22 _MSG STORAGE REGISTRY S Struct Reference 


#include <Msg_Mapi_Storage_Registry.h> 


5.22.1 Detailed Description 


Represents a storage registry entry. 


For details of the storage, please refer to Storage . 


Data Fields 


e MSG_MEDIA_TYPE_T media_type 
e MSG_STORAGE_ID_T storeld 

e bool canDeregister 

e unsigned char x name 

e unsigned char * path 


5.22.2 Field Documentation 


5.22.2.1 MSG MEDIA_TYPE_T MSG STORAGE REGISTRY_S::media_type 


Indicates the storage media 


5.22.2.2 MSG _ STORAGE ID_T_MSG_STORAGE_ REGISTRY _S::storeld 


Indicates the unique storage id 


5.22.2.3 bool _MSG_STORAGE_REGISTRY_S::canDeregister 


Indicates whether the storage can be deregistered 


5.22.2.4 unsigned charx MSG STORAGE REGISTRY_S::name 


Indicates the name of the storage. It’s encoded in ASCII 


5.22.2.5 unsigned charx MSG STORAGE REGISTRY _S::path 


Indicates the path where the storage is located. It is encoded in ASCII 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Storage_Registry.h 
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5.23 _MSG STRING S Struct Reference 


#include <Msg_Mapi_Types.h> 


5.23.1 Detailed Description 


Represents a string. 


Data Fields 


e MSG_ENCODE_TYPE_T encodeType 
e int length 
e unsigned char * pString 


5.23.2 Field Documentation 


5.23.2.1 MSG_ENCODE_TYPE_T_MSG_STRING_S::encodeType 


The encoding type of the string 


5.23.2.2  int_MSG_STRING_S::length 


The length of string value 


5.23.2.3 unsigned chars _MSG_STRING_S::pString 


The string value 


The documentation for this struct was generated from the following file: 


e Msg_Mapi_Types.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


Chapter 6 


File Documentation 


6.1 ComponentOverview.h File Reference 


6.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 


Defines 


e #define COMPONENT_OVERVIEW_H 


6.1.2 Define Documentation 


6.1.2.1 #define COMPONENT_OVERVIEW_H 
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6.2 Msg Mapi_Account.h File Reference 


6.2.1 Detailed Description 


Defines the account structure. 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Folder.h" 


Data Structures 


¢ struct_MSG_ACCOUNT_S 


Represents an account. 


Typedefs 


e typedef struct_MSG_ACCOUNT_S MSG_ACCOUNT_S 


6.2.2 Typedef Documentation 


6.2.2.1 typedef struct _MSG_ACCOUNT_S MSG_ACCOUNT_S 
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6.3 Msg Mapi_Contact.h File Reference 


6.3.1 Detailed Description 


Defines the contact structure. 


#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG _CONTACT_S 


Represents a contact. 


e struct MSG CONTACT _LIST_S 


Represents a contact list. 


Typedefs 


e typedef struct_MSG_CONTACT_S MSG_CONTACT_S 
e typedef struct _MSG_CONTACT_LIST_S MSG_CONTACT_LIST_S 


6.3.2 Typedef Documentation 
6.3.2.1 typedef struct _MSG_CONTACT_LIST_S MSG_CONTACT_LIST_S 


6.3.2.2 typedef struct _MSG_CONTACT_S MSG_CONTACT_S 
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6.4 Msg Mapi_FilterRule.h File Reference 


6.4.1 Detailed Description 


Defines the filter related structures. 


MSG_FILTER_S and MSG_FILTER_LIST_S define the criteria for session’s interested incoming mes- 
sages. 


MSG_FILTER_S represents the basic filter unit, with a pair of filter type and filter value. A filter is satisfied 
when the filter value meets the requirement of specific filter type. 


MSG_FILTER_LIST_S is composed of a series of various MSG_FILTER_S. A filter list is satisfied when 
one of filters in the list satisfied. 


The first filter in the list has the highest priority, the last the lowest. Framework will check the filter list 
from the first to the last. Once an incoming message satisfies one filter in the list, framwork would stop 
checking and return. 


The framework sends the satisfying messages to filter-list associated applications. If the intercept is set 
true, the lower priority session would not receive the messages. 


See MsgPlgFilterCheckRules in Messaging Framework API [2]. 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG FILTER _ID_LIST_S 


Represents a filter id list. 


¢ struct_MSG_FILTER_S 


Represents a filter. 


e struct MSG _FILTER_LIST_S 


Represents a filter list. 


Typedefs 


e typedef int MSG_FILTER_ID_T 
Represents the filter Id. 


e typedef struct _MSG_FILTER_ID_LIST_S MSG_FILTER_ID_LIST_S 
e typedef struct _MSG_FILTER_S MSG_FILTER_S 
e typedef struct _MSG_FILTER_LIST_S MSG_FILTER_LIST_S 


Enumerations 


e enum_MSG_FILTER_ID E ( 


MSG_FILTER_BY_UNKNOWN = 0, MSG_FILTER_BY_MSG_TYPE, MSG_FILTER_BY_- 
FROM, MSG_FILTER_BY_HAS_ATTACHMENT, 
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MSG_FILTER_BY_HAS DRM CONTENT, MSG_FILTER BY_SIZE_GT, MSG_FILTER_- 
BY_SIZE_LT, MSG_FILTER_BY_PRIORITY_GT, 


MSG_FILTER_BY_PRIORITY_LT, MSG_FILTER_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of filter id. 


6.4.2 Typedef Documentation 


6.4.2.1 typedef struct MSG FILTER_ID_LIST_S MSG_FILTER_ID_LIST_S 


6.4.2.2 typedef int MSG_FILTER_ID_T 


Represents the filter Id. 


A filter Id represents a unique filter type. The values for this type SHOULD be in _MSG_FILTER_ID_E 
or other extended filter Ids. 


6.4.2.3 typedef struct _MSG_FILTER_LIST_S MSG_FILTER_LIST_S 


6.4.2.4 typedef struct _MSG_FILTER_S MSG_FILTER_S 


6.4.3 Enumeration Type Documentation 
6.4.3.1 enum_MSG_FILTER_ID_E 


Represents the values of filter id. 
This enum is used as the value of MSG_FILTER_ID_T. 
For example: 

MSG_FILTER_S filter; 


filter.filterld = MSG_FILTER_BY_MSG_TYPE; 
filter.filterValue = (unsigned charx)malloc(sizeof (MSG_MESSAGE_TYPE_S)); 


MSG_MESSAGE_TYPE_S* msgType = (MSG_MESSAGE_TYPE_S*) filter.filterValue; 
msgType->mainType = MSG _MESSAGE_TYPE_SMS; 
msgType->subType = MSG_MESSAGE_TYPE_SMS_TEXT; 


//set the filter 


//the session will only receive SMS. 


Enumerator: 


MSG_FILTER BY UNKNOWN Unknown sort type. 


MSG_FILTER_BY_MSG_TYPE The messages whose message type are filterValue will be 
filtered out. filterValue should be MSG_MESSAGE_TYPE_S type. 


MSG_FILTER_BY_FROM The messages that come from filterValue will be filtered out. fil- 
terValue should be char x type, which is encoded in ASCII. 


MSG_FILTER_BY_HAS_ATTACHMENT Filter by whether the message has attachment. 
If filterValue is set 0, the messages that do not has attachment will be filtered out. 


If filterValue is set 1, the messages that have attachment will be filtered out. 
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MSG_FILTER_BY_HAS_DRM_CONTENT Filter by whether the message has DRM content. 
If filterValue is set 0, the messages that do not has DRM content will be filtered out. 


If filterValue is set 1, the messages that have DRM content will be filtered out. 


MSG_FILTER_BY_SIZE_GT The messages whose size are greater than or equal the 
filterValue will be filtered out. filterValue should be size_t type 


MSG_FILTER_BY_SIZE_LT The messages whose size are less than or equal the fi lterValue 
will be filtered out. filterValue should be size_t type 


MSG_FILTER_BY_PRIORITY_GT The messages whose priority are greater than or equal the 
filterValue will be filtered out. filterValue should be MSG_MESSAGE PRIORITY_T 
type. 

MSG_FILTER_BY_PRIORITY_LT The messages whose priority are less than or equal the 
filterValue will be filtered out. filterValue should be MSG_MESSAGE_PRIORITY_T 
type. 

MSG_FILTER_BY_USER_DEF_BEGIN User defined filter type begin value. 
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6.5 Msg Mapi_Folder.h File Reference 


6.5.1 Detailed Description 


Defines the folder related structures. 
For the detail information of folder , please refer to Folder . 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_QueryRule.h" 


Data Structures 


e struct_MSG_FOLDER_S 


Represents a folder. 


Typedefs 
e typedef struct_MSG_FOLDER_S MSG_FOLDER_S 


6.5.2 Typedef Documentation 


6.5.2.1 typedef struct MSG _FOLDER_S MSG FOLDER S 
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6.6 Msg Mapi_Message.h File Reference 


6.6.1 Detailed Description 


Defines the message structure. 


#incl 
#incl 
#incl 


#incl 


ude 
ude 
ude 


ude 


<stdlib.h> 
"Msg_Mapi_Types.h" 
"Msg_Mapi_Contact.h" 


"time.h" 


Data Structures 


e struct_ MSG_MESSAGE_S 


Represents a message. 


Typedefs 
e typedef struct_MSG_MESSAGE_S MSG_MESSAGE_S 


6.6.2 Typedef Documentation 


6.6.2.1 


typedef struct MSG MESSAGE S MSG_MESSAGE_S 
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6.7 Msg Mapi_Message_Request.h File Reference 


6.7.1 Detailed Description 


Defines the message request structure. 
#include <stdlib.h> 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Message.h" 


Data Structures 


e struct _MSG_ MESSAGE REQUEST_S 


Represents a request that will be sent to messaging framework. 


Typedefs 


e typedef struct_MSG_MESSAGE_REQUEST_S MSG_MESSAGE_REQUEST_S 


6.7.2 Typedef Documentation 


6.7.2.1 typedef struct _MSG_MESSAGE_REQUEST_S MSG_MESSAGE_REQUEST_S 
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6.8 Msg Mapi_Message_Status.h File Reference 


6.8.1 Detailed Description 


Defines the message status structure. 


#include "stdlib.h" 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct_MSG_MESSAGE_STATUS_S 


Represents a message status. 


Typedefs 


e typedef struct_MSG_MESSAGE_STATUS_S MSG_MESSAGE_STATUS_S 


6.8.2 Typedef Documentation 


6.8.2.1 typedef struct _MSG_MESSAGE_STATUS_S MSG_MESSAGE_STATUS_S 
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6.9 Msg Mapi_QueryRule.h File Reference 


6.9.1 Detailed Description 


Defines the query related structure. 


Query rule is used to query some specific messages from storage. Query rule list is composed of various 
query rules. Once the message satisfies one of the query rules in the list, it satisfies the query rule list. 


Applications should assemble a query rule list to filter the message even there is only one query rule. Please 
refer to MSG_QUERY_LIST_S 


Framework storage plugin SHOULD implement the query function and provide the supported queryId and 
query Value for user. 


#include "Msg_Mapi_Types.h" 


Data Structures 


e struct MSG QUERY_ID_LIST_S 


Represents a query Id list. 


e struct _MSG_QUERY_S 


Represents a query rule. 


e struct_MSG_QUERY_LIST_S 


Represents a query list. 


e struct_MSG_SORT_TYPE_LIST_S 


Represents a sort type list. 


e struct_MSG_SORT_RULE_S 


Represents a sort rule. 


Typedefs 


e typedef int MSG_QUERY_ID_T 
The query id. 


e typedef struct _MSG_QUERY_ID_LIST_S MSG_QUERY_ID_LIST_S 
e typedef struct_MSG_QUERY_S MSG_QUERY_S 

» typedef struct _MSG_QUERY_LIST_S MSG_QUERY_LIST_S 

e typedef int MSG_SORT_TYPE_T 


Represents a sort type. 


e typedef struct _MSG_SORT_TYPE_LIST_S MSG_SORT_TYPE_LIST_S 
e typedef struct_MSG_SORT_RULE_S MSG_SORT_RULE_S 
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Enumerations 


e enum _MSG_QUERY_ID_E { 


MSG_QUERY_BY_UNKNOWN = 0, MSG_QUERY_BY_BEFORE_ DATETIME, MSG_- 
QUERY_BY_AFTER_DATETIME, MSG_QUERY_BY_FROM, 


MSG_QUERY_BY_TO, MSG_QUERY_BY_ SUBJECT, MSG _QUERY_BY_SIZE, MSG_- 
QUERY_BY_STATUS, 


MSG_QUERY_BY_DELIVERY_STATUS, MSG _QUERY_BY_HASATTACHMENT, MSG_- 
QUERY_BY_HASDRMCONTENT, MSG_QUERY_BY_PRIORITY, 


MSG_QUERY_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of query Id. 


enum _MSG_SORT_TYPE_E { 


MSG_SORT_BY_UNKNOWN = 0, MSG_SORT_BY_DISPLAY SUBJECT, MSG_SORT_BY_- 
DISPLAY_FROM, MSG_SORT_BY_DISPLAY_TO, 


MSG_SORT_BY_DISPLAY_TIME, MSG_SORT_BY_SIZE, MSG_SORT_BY_STATUS, MSG_- 
SORT_BY_DELIVERY_STATUS, 


MSG_SORT_BY_HASATTACHMENT, MSG_SORT_BY_HASDRMCONTENT, MSG_SORT_- 
BY_PRIORITY, MSG_SORT_BY_USER_DEF_BEGIN = 0x00001000 } 


Represents the values of sort types. 


6.9.2 Typedef Documentation 


6.9.2.1 typedef struct _MSG_QUERY_ID_LIST_S MSG_QUERY_ID_LIST_S 


6.9.2.2 typedef int MSG_QUERY_ID_T 


The query id. 


One query id presents a unique query type. 


6.9.2.3 typedef struct _MSG_QUERY_LIST_S MSG_QUERY_LIST_S 


6.9.2.4 typedef struct _MSG_QUERY_S MSG_QUERY_S 


6.9.2.5 typedef struct MSG SORT_RULE_S MSG_SORT_RULE_S 


6.9.2.6 typedef struct _MSG_SORT_TYPE_LIST_S MSG_SORT_TYPE_LIST_S 
6.9.2.7 typedef int MSG_SORT_TYPE_T 


Represents a sort type. 


The values for this type SHOULD be in _MSG_SORT_TYPE_E 
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6.9.3 Enumeration Type Documentation 
6.9.3.1 enum_MSG_QUERY_ID E 


Represents the values of query Id. 


This enum is used as the value of MSG_QUERY_ID_T, which is used as an input parameter in method Ms- 
gQueryMessage. Framework storage plugin can extend the supported query Id in this enum. Applications 
can use the query Id when querying messages. 


Enumerator: 


MSG_QUERY BY UNKNOWN Unknown query Id 


MSG_QUERY_BY BEFORE_DATETIME Query message whose time is before or equal to the 
datetime. 


MSG_QUERY_BY_AFTER_DATETIME Query message whose time is after or equal to the date- 
time 
MSG_QUERY BY FROM Query message by from_keyword 
MSG_QUERY BY TO Query message by to_keyword 
MSG_QUERY_BY_ SUBJECT Query message by subject_keyword 
MSG_QUERY_BY_SIZE Query message by size 
MSG_QUERY BY STATUS Query message by status 
MSG_QUERY BY DELIVERY STATUS Query message by delivery status 
MSG_QUERY_BY_HASATTACHMENT Query message by has attachment 
MSG_QUERY_BY_HASDRMCONTENT Query message by drm content 
MSG_QUERY_BY_PRIORITY Query message by priority 
MSG_QUERY_BY_USER_DEF_BEGIN User defined query Id begin value 


6.9.3.2 enum _MSG SORT_TYPE_E 


Represents the values of sort types. 


This enum is used as the value of MSG_SORT_TYPE_T. 


Enumerator: 


MSG_SORT_BY_UNKNOWN Unknown sort type 
MSG_SORT_BY DISPLAY SUBJECT Sort by display subject 
MSG_SORT_BY DISPLAY FROM Sort by display from 
MSG_SORT_BY_DISPLAY_TO Sort by display to 
MSG_SORT_BY_DISPLAY_ TIME Sort by display time 
MSG_SORT_BY_SIZE Sort by size 

MSG_SORT_BY STATUS Sort by status 
MSG_SORT_BY_DELIVERY_STATUS Sort by delivery status 
MSG_SORT_BY_HASATTACHMENT Sort by has attachment 
MSG_SORT_BY HASDRMCONTENT Sort by drm content 
MSG_SORT_BY PRIORITY Sort by priority 
MSG_SORT_BY USER_DEF_BEGIN User defined sort type begin value 
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6.10 Msg Mapi_Session.h File Reference 


6.10.1 Detailed Description 


Defines session handling and message sending and receiving related functions. 


i 
i 
as 


i 


i 


nel 
ncl 
nel 
nel 


nel 


ude "Msg_Mapi_Message.h" 
ude "Msg_Mapi_Message_Status.h" 
ude "Msg_Mapi_Message_Request.h" 


ude "Msg_Mapi_Types.h" 


ude "Msg_Mapi_FilterRule.h" 


Typedefs 


typedef struct MessagingSession x MSG_SESSION_HANDLE_T 


Defines a session handle. 


typedef void(* MsgOnMessageIncomingCallback )(MSG_MESSAGE_S xpMsglnfo, MSG_- 
MESSAGE_STATUS_S x*pMsgStatus, MSG_SESSION_HANDLE_T hSession) 


Prototype of the function that will be called when a new message received. 


typedef void(* MsgOnStatusChangedCallback )(MSG_MESSAGE STATUS_S x*pMsgStatus, 
MSG_SESSION_HANDLE_T hSession) 


Prototype of the function that will be called when status changed. 


Functions 


MSG_ERROR_T MsgCreateSession (MSG_SESSION_HANDLE_T xhSession) 


Creates a session handle. 


MSG_ERROR_T MsgDestroySession (MSG_SESSION_HANDLE_T hSession) 


Destroys the session handle. 


MSG_ERROR_T MsgRegMessageCallback (MSG_SESSION_HANDLE_T hSession, MsgOnMes- 
sageIncomingCallback onMsgIncoming) 


Registers MsgOnMessagelncoming Callback function to the session handle. 


MSG_ERROR_T MsgRegStatusCallback (MSG_SESSION_HANDLE_T hSession, MsgOnSta- 
tusChangedCallback OnStatusChanged) 


Registers MsgOnStatusChangedCallback to the session handle. 


MSG_ERROR_T MsgConnectSession (MSG_SESSION_HANDLE_T hSession) 


Connects the session handle. 


MSG_ERROR_T MsgDisconnectSession (MSG_SESSION_HANDLE_T hSession) 


Disconnects the session handle. 
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MSG_ERROR_T MsgSetPriority (MSG_SESSION_HANDLE_T hSession, MSG_SESSION_- 
PRIORITY_T priority) 


Sets priority for the session handle. 


MSG_ERROR_T MsgSetFilterList (MSG_SESSION_HANDLE_T hSession, const MSG_- 
FILTER_LIST_S xpFilterList) 


Sets filter list to the session handle. 


MSG_ERROR_T MsgSubmitReq (MSG_SESSION_HANDLE_T hSession, const MSG_- 
MESSAGE_REQUEST_S *pReq, MSG_REQUEST_ID_T xpRegld) 


Submits a request. 


MSG_ERROR_T MsgCancelReq (MSG_SESSION_HANDLE_T hSession, MSG_REQUEST_- 
ID_T reqld) 


Cancels a request by request id. 


MSG_ERROR_T MsgGetAllSupportedMsgType (MSG_MESSAGE_TYPE_LIST_S 
*pMsgTypeList) 


Gets all supported message types. 


void MsgReleaseMsgTypeList (MSG_MESSAGE_TYPE_LIST_S x*pMsgTypeList) 


Releases the memory of message type List. 


MSG_ERROR_T MsgGetAllSupportedFilterld (MSG_FILTER_ID_LIST_S xpFilterldL ist) 
Gets all supported filter id. 


void MsgReleaseFilterldList (MSG_FILTER_ID_LIST_S xpFilterIdList) 


Releases the memory of filter Id List. 


MSG_PLUGIN_ERROR_T MsgGetSessionPluginError (MSG_SESSION_HANDLE_T hsSes- 
sion) 


Get session specific plugin error. 


6.10.2 Typedef Documentation 
6.10.2.1 typedef struct MessagingSessions MSG_SESSION_HANDLE_T 


Defines a session handle. 


For details of Session, please refer to Session 


6.10.2.2 typedef void(« MsgOnMessageIncomingCallback)(MSG_MESSAGE S «pMsgInfo, 
MSG _ MESSAGE_STATUS_S «pMsgStatus, MSG_SESSION_HANDLE_T hSession) 


Prototype of the function that will be called when a new message received. 


Applications SHOULD implement this callback function and register it into a session handle. For how 
to register this callback function, please refer to MsgRegMessageCallback. This callback function will 
be called when a new message received and the message satisfies the filter list which is attached to the 
session handle. The callback function runs in application process, not in framework process. The memory 
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for pMsgInfo and pMsgStatus are managed by MAPI, when the callback function is finished, the 
memory will be released by MAPI automatically. 
Parameters: 


<— pMsgInfo is a pointer to the received message. 
— pMsgStatus is a pointer to the status. 


— hSession is a session handle. It indicates which session is invoked. 


Returns: 


void 


Please refer to Callback Functions 


Since: 


1.0 


6.10.2.3 typedef void(* MsgOnStatusChangedCallback)(MSG_MESSAGE_STATUS_S 
x«pMsgStatus, MSG_SESSION_HANDLE_T hSession) 
Prototype of the function that will be called when status changed. 


Applications SHOULD to implement this callback function and register it into a session handle. For how 
to register this callback function, please refer to MsgRegStatusCallback. For instance, if application sends 
a message, this callback function will be called to report sending status. Application can get the request id 
from pMsgStatus to know which request the status is bound. The callback function runs in user application 
process, not in framework process. The memory of pMsgSt atus is managed by MAPI, when the callback 
function is finished, the memory will be released by MAPI automatically. 

Parameters: 


— pMsgStatus is a pointer to the status. 


— hSession is a session handle. It indicates which session is invoked. 


Returns: 


void 


Note: 


Please refer to Callback Functions 


Since: 


1.0 


6.10.3 Function Documentation 


6.10.3.1 MSG _ERROR_T MsgCancelReq (MSG_SESSION_HANDLE_T hSession, 
MSG_REQUEST_ID_T regld) 


Cancels a request by request id. 
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If cancel successfully, status "MSG_STATUS_REQ_ CANCELLED" will be sent back. If cancel failed, no 
special status will be sent back. 


If regld is invalid, MSG_ERR_INVALID_REQUEST_ID will be returned. 


This is an asynchronous function. 


Parameters: 


— hSession is a pointer to an established session handle. 


— reqld is the request id of the request to be cancelled. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS submits the "cancel request" request to framework successfully. 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_SESSION_NOT_CONNECTED session is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 

MSG_ERR_INVALID_REQUEST_ID request id is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetSessionPluginError() to get 
detail error code. 


Note: 


The result information will be sent back by using callback function MsgOnStatusChangedCallback 


Since: 


1.0 


6.10.3.2 MSG_ERROR_T MsgConnectSession (MSG_SESSION_HANDLE_T hSession) 


Connects the session handle. 

This function MUST be called after session handle is created. 

It is the precondition to call functions MsgSubmitReq, MsgSetPriority, MsgSetFilterList, MsgCancelReq 
and MsgGetAlSupportedFilterld 

Parameters: 


— hSession is a pointer to an session handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS connects the session handle successfully. 
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MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.10.3.3 MSG_ERROR_T MsgCreateSession (MSG_SESSION_HANDLE_T x hSession) 


Creates a session handle. 


This function creates a session handle. Each application can call this function multiple times to create 
more than one session handles. All session handles are independent. For details of session, please refer to 
Session. 


Parameters: 
— hSession is a pointer to a session handle. When this function returns MSG_SUCCESS, 
*hSession will be valid session handle. Otherwise, it will be NULL. 
Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS creates session handle successfully. 
MSG_ERR_NULL_POINTER the input parameter is NULL. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.10.3.4 MSG _ERROR_T MsgDestroySession (MSG_SESSION_HANDLE_T hSession) 


Destroys the session handle. 


This function destroys a session handle. This function releases resources and disconnects session if it’s 
connected. Once a session handle is destroyed, it can’t be used any more. For each created session, 
applications MUST destroy it, when it’s not used any more. If the input parameter is NULL, this function 
does nothing and returns MSG_ERR_INVALID_SESSION_HANDLE. 


Parameters: 


— hSession is a pointer to an session handle to be destroyed. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS destroyes the handle successfully. 
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MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 


Since: 


1.0 


6.10.3.5 MSG_ERROR_T MsgDisconnectSession (MSG_SESSION_HANDLE_T hSession) 


Disconnects the session handle. 


If the session is NULL, this function does nothing and returns MSG_ERR_INVALID_SESSION_- 
HANDLE. 


Parameters: 


— hSession is a pointer to an session handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS disconnects the session handle successfully. 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_SESSION_NOT_CONNECTED the session handle is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.10.3.6 MSG ERROR_T MsgGetAllSupportedFilterld (MSG_FILTER_ID_LIST_S + 
pFilterIdList) 


Gets all supported filter id. 


Parameters: 


> pFilterIdList is a pointer to a filter id list. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS gets all supported filter id successfully. 

MSG_ERR_NULL_POINTER pFilterldList is NULL. 

MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error 
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6.10.3.7 MSG ERROR_T MsgGetAllSupportedMsgType (MSG_MESSAGE_ TYPE_LIST_S x 
pMsgTypeList) 


Gets all supported message types. 


Parameters: 


— pMsgTypeList is a pointer to a message type list. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS gets all supported message types successfully. 
MSG_ERR_NULL_POINTER pMsgTypeList is NULL. 

MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error 


6.10.3.8 MSG PLUGIN_ERROR_T MsgGetSessionPluginError (MSG_SESSION_HANDLE_T 
hSession) 

Get session specific plugin error. 

This function is to get the specific plugin error. In case that some functions return MSG_ERR_PLUGIN, 

applications can call this function immediately to get specific error code of the plugins. If hSession is 

invalid, this function will return 0. 

Parameters: 


— hSession is a pointer to an established session handle. 


Returns: 


MSG_PLUGIN_ERROR_T 


6.10.3.9 MSG_ERROR_T MsgRegMessageCallback (MSG_SESSION_HANDLE_T hSession, 
MsgOnMessagelncomingCallback onMsgIncoming) 
Registers MsgOnMessageIncomingCallback function to the session handle. 


Applications SHOULD implement the function MsgOnMessagelncomingCallback. For details, please 
refer to MsgOnMessageIncomingCallback 


Applications MAY deregister the callback function MsgOnMessageIncomingCallback by invoking this 
function like MsgRegMessageCallback (hSession, NULL). 


This function MUST be called after session handle is created. It makes no difference to call this function 
before or after session connected. This function can be called more times and the last inovking will be 
effective. 


Parameters: 


— hSession is a pointer to an session handle. 
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< onMsgIncoming is a function pointer to an implemenation function. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS registers the call back function successfully 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_MEMORY_ERROR memory is error. 

Since: 


1.0 


6.10.3.10 MSG ERROR_T MsgRegStatusCallback (MSG_SESSION_HANDLE_T /Session, 
MsgOnStatusChangedCallback OnStatusChanged) 
Registers MsgOnStatusChangedCallback to the session handle. 


Applications SHOULD implement the function MsgOnStatusChangedCallback. For details, please refer 
to MsgOnStatusChangedCallback 


Applications MAY deregister the callback function MsgOnStatusChangedCallback by invoking this func- 
tion like MsgRegStatusCallback (hSession, NULL). 


This function MUST be called after session handle is created. It makes no difference to call this function 
before or after session connected. This function can be called more times and the last invoking will be 
effetive. 


Parameters: 

— hSession is a pointer to an session handle. 

— OnStatusChanged is a function pointer to an implemenation function. 
Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS registers the call back function successfully. 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_MEMORY_ERROR memory is error. 

Since: 


1.0 


6.10.3.11 void MsgReleaseFilterIdList (MSG_FILTER_ID_LIST_S x pFilterldList) 


Releases the memory of filter Id List. 
This function releases the memory of filterlds in MSG_FILTER_ID_LIST_S structure. 


If pFilterIdList or pFilterIdList->filterlds is NULL, nothing happens. If pFilterldList or pFilterIdList- 
>filterIds is invalid, undefined behavior. 
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Note: 


This function only frees the list pointer member inside the structure. It doesn’t free the structure itself. 


Parameters: 


— pFilterIdList is a pointer to an MSG_FILTER_ID_LIST_S structure. 


Since: 


1.0 


6.10.3.12 void MsgReleaseMsgTypeList (MSG_MESSAGE TYPE_LIST_S « pMsgTypeList) 


Releases the memory of message type List. 

This function releases the memory of pMsgTypes in MSG_MESSAGE_TYPE_LIST_S structure. If pMs- 
gTypeList or pMsgTypeList->pMsgTypes is NULL, nothing happens. If pMsgTypeList or pMsgTypeList- 
>pMsgTypes is invalid, undefined behavior. 

Note: 


This function only frees the list pointer member inside the structure. It doesn't free the structure itself. 


Parameters: 


— pMsgTypeList is a pointer to a MSG_MESSAGE_TYPE_LIST_S structure. 


Since: 


1.0 


6.10.3.13 MSG _ERROR_T MsgSetFilterList (MSG_SESSION_HANDLE_T hSession, const 
MSG_FILTER_LIST_S sx pFilterList) 


Sets filter list to the session handle. 


This function sets the filter list to a session handle. It impacts the callback functions. Only the received 
messages satisfying one filter in the filter list can be passed up to the callback function. Otherwise, the 
callback function will not be called. For details of filter list, please refer to MSG_FILTER_LIST_S 


This function MUST be called after session is created and connected. This function can be called more 
times and the last one will be effective. If no filter list is set to the session or pFilterList is NULL, all the 
messages will be received by the session. 

Parameters: 


— hSession is a pointer to an established session handle. 


— pFilterList is a pointer to the filter list for the session handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS sets the filter list successfully. 
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MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_SESSION_NOT_CONNECTED the session handle is not connected. 
MSG_ERR_INVALID_FILTER_ID the filter id in pFilterList is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.10.3.14 MSG_ERROR_T MsgSetPriority (MSG_SESSION_HANDLE_T hSession, 
MSG_SESSION_PRIORITY_T priority) 


Sets priority for the session handle. 
This function sets the priority for a session handle. The following use case shows the usage of priority: 


When a messaging is received, if this message satisfies the filter rule of this session and intercept of the 
satisfied filter rule is set true, this message will be passed to this session callback function and will not be 
passed to lower priority session callback functions. 


All the sessions will receive the messages if they have same priority. 
For details of intercept, please refer to Intercept. 


This function MUST be called after session is created and connected. This function can be called more 
times and the last invoking will be effective. 


If this function is not called, the default priority is MSG_SESSION_PRIORITY_NORMAL. 


Parameters: 
— hSession is a pointer to a session handle. 


— priority is for the session handle. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS sets the priority successfully. 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_SESSION_NOT_CONNECTED the session handle is not connected. 
MSG_ERR_INVALID_SESSION_PRIORITY the priority is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 
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6.10.3.15 MSG ERROR_T MsgSubmitReq (MSG_SESSION_HANDLE_T hSession, const 
MSG_MESSAGE_REQUEST_S + pReg, MSG_REQUEST_ID_T x pReqld) 


Submits a request. 


To submit a request, applications need to specify the reqType in request structure: For example, to send a 
message, applications need to set reqType with value MSG_REQUEST_TYPE_SEND. 


regla will be filled by this function automatically and return to application. 


Following is the sample code to send a message: 


MSG_SESSION_HANDLE_T session; 
MSG_MESSAGE_REQUEST_S req; 
MSG_MESSAGE_S msg; 

//.... init session and msg. 

//Set request type 

reg.regType = MSG_REQUEST_TYPE_SEND; 
//Set msg 

req.mpMsg = &msg; 

//Submit request. 
MsgSubmitReq(session, &req); 


Message plugins can extend the request types to provide more functions. Please refer to enum MSG_- 
REQUEST_TYPE_T to define the extended request types. When applications submit these requests, the 
framework will pass the requests to the underlaying plugins. 


If pReq->reqType is invalid, an asynchronous status with error "MSG_ERR_INVALID_REQUEST" will 
be sent back. 


For request type "MSG_REQUEST_TYPE_SEND" and "MSG_REQUEST_TYPE_SENDSAVE": 


Applications MUST fill valid message type for field pReq->msgType, otherwise, MSG_ERR_INVALID_- 
REQUEST will be returned immediately. 


° If pReq->pMsg->accountld is MSG_DEFAULT_ACCOUNT_ID, then the default account is used. 


¢ If pReq->pMsg->accountld is not valid, the function returns "MSG_ERR_INVALID_REQUEST". 


For request type "MSG_REQUEST_TYPE_SEND", following fields will be ignored: 
pReq->pMsg->msgld, pReq->pMsg->parentld, pReq->pMsg->storageld. 


For request type "MSG_REQUEST_TYPE_SENDSAVE", if valid pReq->pMsg->parentld and pReq- 
>pMsg->storageld are given, they override the default values in account information. If pReq->pMsg- 
>parentId is MSG_DEFAULT_FOLDER_ID, the message will be added to the outbox in its associated 
account. If pReq->pMsg->storageld is MSG_STORAGE_ DEFAULT, the message will be added to the 
defaultMsgStorageld in its associated account. 


This is an asynchronous function. 


Parameters: 
— hSession is a pointer to an established session handle. 
— pReg is the request to be submitted. 


=> pReqld is the id of this request. This id is assigned by framework automatically. Applications can 
keep this id and use MsgCancelReq to cancel the request. 
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Returns: 


MSG_ERROR_T. 


Return values: 


MSG_SUCCESS submits the request to framework successfully. 
MSG_ERR_NULL_POINTER pReq is NULL or pReqld is NULL. 
MSG_ERR_INVALID_SESSION_HANDLE the session handle is invalid. 
MSG_ERR_SESSION_NOT_CONNECTED session is not connected. 


MSG_ERR_INVALID_REQUEST the message type in request is invalid. For request type "MSG_- 
REQUEST_TYPE_SENDSAVE", some mandatory fields are invalid. 


MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetSessionPluginError() to get 
detail error code. 
Note: 


The result information will be sent back by using callback function MsgOnStatusChangedCallback. 


Since: 


1.0 
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6.11 Msg Mapi_Storage_Account.h File Reference 


6.11.1 Detailed Description 


Defines account related functions. 


This file includes all MAPI account functions, such as creating, updating, querying, and deleting account. 


There are also some functions used to set and get default account id. 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Account.h" 


#include "Msg_Mapi_Storage_Manager.h" 


Functions 


MSG_ERROR_T MsgAddAccount (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
ACCOUNT_S x*pAccount) 


Adds a new account. 


MSG_ERROR_T MsgUpdateAccount (MSG_CONNECTION_HANDLE_T hConnection, const 
MSG_ACCOUNT_S xpAccount) 


Updates an account. 


MSG_ERROR_T MsgDeleteAccount (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
ACCOUNT_ID_T accountld, bool delRootFolder) 


Deletes an account. 


MSG_ERROR_T MsgCountAccount (MSG_CONNECTION_HANDLE_T hConnection, const 
MSG_MESSAGE_TYPE_S «pMsgType, int *xpCount) 


Gets the number of accounts for the specified message type. 


MSG_ERROR_T MsgQueryAccount (MSG_CONNECTION_HANDLE_T hConnection, const 
MSG_MESSAGE_TYPE_S *pMsgType, MSG_ACCOUNT_ID_LIST_S x*pAccountIdList) 


Queries account id list for the specified message type. 


MSG_ERROR_T MsgGetAccount (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
ACCOUNT_ID_T accountld, MSG_ACCOUNT_S **ppAccount) 


Gets the detailed account information for the specified account. 


void MsgRelease Account (MSG_ACCOUNT_S x*pAccount) 


Releases the memory of an account structure. 


MSG_ERROR_T MsgGetCommAccount (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_ACCOUNT_ID_T accountld, MSG_ACCOUNT_S x**ppAccount) 


Gets account common information. 


void MsgReleaseCommAccount (MSG_ACCOUNT_S *pAccount) 


Releases account common information. 
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const MSG_MESSAGE_TYPE_S «pMsgType, MSG_ACCOUNT_ID_T x*pAccountld) 


Gets the default account id. 


const MSG_MESSAGE_TYPE_S x*pMsgType, MSG_ACCOUNT_ID_T accountld) 


Sets the default account id. 


void MsgReleaseAccountIdList (MSG_ACCOUNT_ID_LIST_S x*pAccountldList) 


Release the memory of an account id list. 


tion, MSG_STORAGE_ID_T storageld, MSG_ACCOUNT_ID_LIST_S x*pAccountIdList) 


Gets all the account ids on a specified storage. 


MSG_ACCOUNT_ID_T accountld, MSG_STORAGE ID_T storageld) 


Moves an account to the specified storage. 


6.11.2 Function Documentation 


6.11.2.1 MSG _ERROR_T MsgAddAccount (MSG_CONNECTION_HANDLE_T hConnection, 


MSG_ACCOUNT_S + pAccount) 


Adds a new account. 


MSG_ERROR_T MsgGetDefaultAccountID (MSG_CONNECTION_HANDLE_T hConnection, 


MSG_ERROR_T MsgSetDefaultAccountID (MSG_CONNECTION_HANDLE_T hConnection, 


MSG_ERROR_T MsgGetAccountIdsByStorage (MSG_CONNECTION_HANDLE_T hConnec- 


MSG_ERROR_T MsgMoveAccountToStorage (MSG_CONNECTION_HANDLE_T hConnection, 


This function adds an account into storage. Application fills all the account information into the account 
structure pAccount except for field account Id. The account Id SHOULD have no value, and after 
the account is successfully created, it will be filled with the new generated account id. Mandatory fields of 
account structure MUST be valid, otherwise the function will be failed. The mandatory fields for adding 


operation are msgType, rootFolderld, storageld, defaultMsgStorageld. 


Parameters: 


< hConnection is a connection handle. 


«> pAccount is the data user defined for this new account. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pAccount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_ACCOUNT The mandatory fields of account structure are invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
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MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX NUMBER_REACHED max number reached. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For the sample code, please refer to Account Storage: Creating and Storing an Account. 


Since: 


1.0 


6.11.2.2 MSG _ERROR_T MsgCountAccount (MSG_CONNECTION_HANDLE_T Connection, 
const MSG_MESSAGE _ TYPE S x pMsgType, int x pCount) 
Gets the number of accounts for the specified message type. 


This function gets the number of accounts for the specified message type, such as SMS, MMS, and Email 
account. If the pMsgType is NULL, the function will return the number of all accounts. If the pMsgType 
is a specific type, it will return the number of accounts of that type. If the pMsgType can’t match with 
anyone above, the function is failed. 


Parameters: 
— hConnection is a connection handle. 
— pMsgType is a pointer to the specified message type. 


— pCount is a pointer to the account number. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.11.2.3 MSG _ERROR_T MsgDeleteAccount (MSG_CONNECTION_HANDLE_T Connection, 
MSG_ACCOUNT_ID_T accountId, bool delRootFolder) 


Deletes an account. 
This function deletes an account by account id. 


If delRootFolder is FALSE, the function will only delete the account and will not delete the root folder. In 
this case, MSG_SUCCESS will be returned. 


If delRootFolder is TRUE and the root folder of this account is not associated with other account(s), this 
function will delete both account and the root folder(including all the content inside). If the root folder 
is associated with other account(s), this function will only delete the account and will not delete the root 
folder. In this case, MSG_ERR_ROOTFOLDER_INUSE will be returned. 


Parameters: 
— hConnection is a connection handle. 
— accountld indicates the specific account need to be deleted. 


— delRootFolder indicates whether delete the associated root folder and the content inside. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_ROOTFOLDER_INUSE This account is deleted, but the root folder is not deleted. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 

MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 


detail error code. 
Since: 


1.0 


6.11.2.4 MSG_ERROR_T MsgGetAccount (MSG_CONNECTION_HANDLE_T Connection, 
MSG_ACCOUNT_ID_T accountId, MSG_ACCOUNT_S xx ppAccount) 
Gets the detailed account information for the specified account. 


This function gets all the detailed account information for the specified account, including common and 
extended data. The memory of out parameter ppAccount is allocated in this function. Application 
SHOULD use function MsgRelease Account to release its memory explicitly. However if this function is 
failed, the memory is NOT allocated in this function. 


Parameters: 


— hConnection is a connection handle. 
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— accountld identifies the queried account. 


— ppAccount is a pointer to a pointer to the account structure which contains all this account detail 
information. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppAccount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.11.2.5 MSG_ERROR_T MsgGetAccountIdsByStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_T storageld, MSG_ACCOUNT_ID_LIST_S x 
pAccountIdList) 


Gets all the account ids on a specified storage. 


This function gets all account ids on a specified storage.The parameter pAccount IdList is defined out- 
side this funtion, but the memory of its field account Ids is allocated in this function. The function caller 
SHOULD use function MsgReleaseAccountIdList to release account Ids memory explicitlly. However 
if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
< hConnection is a connection handle. 
— storageld indicates the queried storage. 


> pAccountldList is a pointer to the account id list. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pAccount IdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
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MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.11.2.6 MSG _ERROR_T MsgGetCommAccount (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_ACCOUNT_ID_T accountId, MSG_ACCOUNT_S xx ppAccount) 


Gets account common information. 


This function gets the account common information. The account common information includes all fields 
of structure MSG_ACCOUNT_S except for pExData. The memory block of out parameter ppAccount 
is allocated in this function. Application SHOULD use function MsgReleaseCommAccount to release its 
memory explicitly. However if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— accountld iendtifies the queried account. 


— ppAccount is a pointer to a pointer to the structure which contains all the account common infor- 
mation. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppAccount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


72 File Documentation 


6.11.2.7 MSG _ERROR_T MsgGetDefaultAccountID (MSG_CONNECTION_HANDLE_T 
hConnection, const MSG_MESSAGE_TYPE_S + pMsgType, MSG_ACCOUNT_ID_T = 
pAccountlId) 


Gets the default account id. 


This function gets the default account id for the specified message type. The parameter pMsgType cannot 
be NULL, for each message type has one default account. 


Parameters: 
— hConnection is a connection handle. 
— pMsgType is a pointer to the specified message type. 


> pAccountld is a pointer to the default account id. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsgType or pAccount Id is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 


detail error code. 
Since: 


1.0 


6.11.2.8 MSG_ERROR_T MsgMoveAccountToStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_ACCOUNT_ID_T accountld, MSG_STORAGE_ID_T storageld) 
Moves an account to the specified storage. 


This function moves an account from a storage to the specified storage. 


Parameters: 
— hConnection is a connection handle. 
— storageld indicates the destination storage. 


— accountld indicates the moved account. 


Returns: 


MSG_ERROR_T 
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Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.11.2.9 MSG _ERROR_T MsgQueryAccount (MSG_CONNECTION_HANDLE_T hConnection, 
const MSG_MESSAGE_TYPE_S x pMsgType, MSG_ACCOUNT_ID_LIST_S + 
pAccountIdList) 


Queries account id list for the specified message type. 


This function gets account id list for the specified message type. The paramether pAccountIdList 
memory is allocated by the function caller, but the memory of its field account Ids is allocated in this 
function, Application SHOULD use function MsgReleaseAccountlIdList to release the memory explicitly. 
However if this function is failed, the memory is NOT allocated in this function. 


If the pMsgType is NULL, this function will return all account id list. If the pMsgType is a specific type, 
this function will return account id list of that type. If the pMsgType cann’t match with anyone above, 
this function is failed. 


Parameters: 
— hConnection is a connection handle. 
< pMsgType is a pointer to the specified message type. 


> pAccountldList is a pointer to the list of account id. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pAccount IdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
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MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.11.2.10 void MsgReleaseAccount (MSG ACCOUNT _S * pAccount) 


Releases the memory of an account structure. 


This function releases the memory of an account structure. If pAccount is NULL, nothing happens. If 
pAccount is invalid, undefined behavior. 


Parameters: 


— pAccount is a pointer to an account structure. 


Since: 


1.0 


6.11.2.11 void MsgReleaseAccountIdList (MSG_ACCOUNT_ID_LIST_S x pAccountldList) 


Release the memory of an account id list. 


This function frees the memory of pointer accountIds inside MSG_ACCOUNT_ID_LIST_S. If 
pAccountldList or pAccountIdList->accountlds is NULL, nothing happens. If pAccountIdList or 
pAccountIdList->accountlds is invalid, undefined behavior. 


Note: 
This function does NOT free this structure itself. 
Parameters: 


— pAccountldList points to a account id list. 


Since: 


1.0 


6.11.2.12 void MsgReleaseCommAccount (MSG_ACCOUNT_S x pAccount) 


Releases account common information. 


This function releases the memory of account common information , which is allocated in function 
MsgGetCommAccount. The account common information includes all the members of structure MSG_- 
ACCOUNT_S except for pExData. If pAccount is NULL, nothing happens. If pAccount is invalid, 
undefined behavior. 


Parameters: 


— pAccount is a pointer to an account structure which only contains common information. 


Since: 


1.0 
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6.11.2.13 MSG ERROR_T MsgSetDefaultAccountID (MSG_CONNECTION_HANDLE_T 
hConnection, const MSG_MESSAGE_TYPE_S « pMsgType, MSG_ACCOUNT_ID_T 
accountld) 


Sets the default account id. 


This function sets the default account id for the specified message type. The parameter pMsgType cannot 
be NULL, for each message type has one default account. 


Parameters: 
— hConnection is a connection handle. 
— pMsgType is a pointer to the specified message type. 


— accountld is the account id which is to be set as the default account. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsgType is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE The message type is not valid. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Example code Account Storage: Getting a Default Account 


Since: 


1.0 


6.11.2.14 MSG_ERROR_T MsgUpdateAccount (MSG_CONNECTION_HANDLE_T 
hConnection, const MSG_ACCOUNT_S + pAccount) 
Updates an account. 


The function is expected to update msgType, rootFolderld, and defaultMsgStorageID for the account in- 
dentified by the given accountld as long as the given values are valid. Optionally, the function updates 
extension data given by pExtData and extDataSize, and accountName, if necessary. 


All the data fields, except foraccount Id and storageld, can be updated. 


Parameters: 


— hConnection is a connection handle. 
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— pAccount is the data user defined to update the account 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pAccount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_ACCOUNT_ID This account is not exist. 
MSG_ERR_INVALID_ACCOUNT The mandatory fields except accountld are invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For the sample code, please refer to Account Storage: Updating an Account 


Since: 


1.0 
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6.12 Msg Mapi_Storage_Folder.h File Reference 


6.12.1 Detailed Description 


Defines folder related functions in MAPI. 


This file includes all folder functions, such as creating, updating, queryring, deleting folder. For the 
overview on folder, please refer to Folder . 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Folder.h" 


#include "Msg_Mapi_Storage_Manager.h" 


Functions 


MSG_ERROR_T MsgAddFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_S xpFolder) 


Adds a new folder. 


MSG_ERROR_T MsgCreateRootFolder (MSG_CONNECTION_HANDLE_T  hConnection, 
MSG_FOLDER_S xpFolder) 


Creates a new root folder. 


MSG_ERROR_T MsgUpdateFolder (MSG_CONNECTION_HANDLE_T hConnection, const 
MSG_FOLDER_S xpFolder) 


Updates a folder. 


MSG_ERROR_T MsgDeleteFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T folderld, bool recursive) 


Deletes a folder. 


MSG_ERROR_T MsgCountSubFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T folderld, int *xpCount) 


Gets the number of sub folders under the specified folder. 


MSG_ERROR_T MsgCountSubFolderRecursive (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_FOLDER_ID_T folderld, int *pCount) 


Gets the number of sub folders under the specified folder. 


MSG_ERROR_T MsgQueryFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T folderld, int iBeginPos, int iCount, MSG_FOLDER_ID_LIST_S *pFolderIdList) 


Queries sub folder ids under the specified folder. 


MSG_ERROR_T MsgQueryFolderRecursive (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_FOLDER_ID_T folderld, int iBeginPos, int iCount, MSG_FOLDER_ID_LIST_S 
*pFolderIdList) 


Recursively queries sub folder ids under the specified folder. 


MSG_ERROR_T MsgMoveFolderToFolder (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T folderld, MSG_FOLDER_ID_T destFolderld) 
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Moves a folder to the specified folder. 


MSG_ERROR_T MsgMoveFolderToStorage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T folderld, MSG_STORAGE_ID_T destStorageld) 


Moves a folder to another storage. 


MSG_ERROR_T MsgGetFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T folderId, MSG_FOLDER_S x*x*ppFolderInfo) 


Gets the folder information of the specified folder. 


MSG_ERROR_T MsgGetFolderByType (MSG_CONNECTION_HANDLE_T  hConnection, 
MSG_FOLDER_ID_T rootFolderld, MSG_FOLDER_TYPE_T folderType, MSG_FOLDER_ID_- 
LIST_S xpFolderldList) 


Gets the folder by folder type for the specified root folder. 


MSG_ERROR_T MsgGetPredefinedFolders (MSG_CONNECTION_HANDLE_T  hConnec- 
tion, MSG_FOLDER_ID_T rootFolderld, MSG_FOLDER_S **xppInbox, MSG_FOLDER_S 
*x*ppOutbox, MSG_FOLDER_S xx*ppDraft, MSG_FOLDER_S **ppSent, MSG_FOLDER_S 
**ppDeleted) 


Gets the predefined folders for the specified root folder. 


MSG_ERROR_T MsgGetFolderParentlId (MSG_CONNECTION_HANDLE_T  hConnection, 
MSG_FOLDER_ID_T folderld, MSG_FOLDER_ID_T *pParentFolderld) 


Gets the parent folder id of a folder. 


void MsgReleaseFolder (MSG_FOLDER_S xpFolderInfo) 


Releases a memory block of a folder structure. 


void MsgReleaseFolderIdList (MSG_FOLDER_ID_LIST_S *pFolderIdList) 
Releases a memory block of folder id list. 


MSG_ERROR_T MsgGetAllRootFolderlds (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_LIST_S *pFolderIdList) 


Get all root folders. 


MSG_ERROR_T MsgGetFolderldsByStorage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_STORAGE_ID_T storageld, MSG_FOLDER_ID_LIST_S xpFolderlIdList) 


Get all the folder id list on a specified storage. 


6.12.2 Function Documentation 


6.12.2.1 MSG_ERROR_T MsgAddFolder (MSG_CONNECTION_HANDLE_T hConnection, 


MSG_FOLDER _S x pFolder) 


Adds a new folder. 


This function creates a folder under the specified parent folder. This function can only create user de- 
fined folder, and not work for root and predefined folder. Mandatory fields of folder structure MUST be 
valid, otherwise the function will be failed. The mandatory fields for adding operation are parent Id, 
storageld, folderType. If the sortType is invalid, the default value MSG_SORT_BY_UNKNOWN 
will be set. 
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Parameters: 


— hConnection is a connection handle. 


«= pFolder points to the data user defined for the new folder. 
pFolder->folderld will be set to a valid folder id in storage when this function is returned suc- 
cessfully. 


Note: 


pFolder->folderld = MSG_INVALID_ID [IN] 
pFolder->folderld = Valid folder id in storage. [OUT] 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pFolder is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_TYPE Folder type is not valid for this operation. 
MSG_ERR_INVALID_FOLDER The value of mandatory fields are invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For sample code, please refer to: 
e Folder Storage: Creating and Storing a Folder 


Since: 


1.0 


6.12.2.2 MSG_ERROR_T MsgCountSubFolder (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderld, int x pCount) 
Gets the number of sub folders under the specified folder. 


This function gets the number of sub folders, and it will not recursively search all the sub folders under the 
specified folder. 
Parameters: 


— hConnection is a connection handle. 
— folderld identifies the specified folder. 
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— pCount returns the number of the sub folders. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pCount is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.3 MSG_ERROR_T MsgCountSubFolderRecursive (USG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderld, int x pCount) 


Gets the number of sub folders under the specified folder. 


This function gets the number of sub folders, and it will recursively search all the sub folders under the 
specified folder. 


Parameters: 


— hConnection is a connection handle. 
— folderld identifies the specified folder. 
— pCount is a pointer to the number of the sub folders. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pCount is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.12.2.4 MSG _ERROR_T MsgCreateRootFolder (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_S x pFolder) 


Creates a new root folder. 


This function creates a new root folder at the application top level, and then creates five predefined fold- 
ers(inbox/outbox/sent/deleted/draft) under this new root folder. It will return success when the root folder 
and its five predefined folders are all created successfully. Messaging application can has more than one 
root folders. Mandatory fields of folder structure MUST be valid, otherwise the function will be failed. 
The mandatory fields for adding operation are parent Id, storageld, folderType. If the sortType 
is invalid, the default value MSG_SORT_BY_UNKNOWN will be set. 


Parameters: 


< hConnection is a connection handle. 


> pFolder points to the data user defined for the new folder. 


pFolder->folderld will be set to a valid folder id in storage when this function is returned suc- 
cessfully. 


Note: 


pFolder->folderld = MSG_INVALID_ID [IN] 
pFolder->folderId = Valid folder id in storage. [OUT] 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pFolder is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 


MSG_ERR_INVALID_FOLDER_TYPE Folder type is invalid. (In this case, it MUST be MSG_- 
FOLDER_TYPE_ROOT.) 


MSG_ERR_INVALID_FOLDER Folder information is invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.5 MSG_ERROR_T MsgDeleteFolder (MSG_CONNECTION_HANDLE_T Connection, 
MSG_FOLDER_ID_T folderld, bool recursive) 


Deletes a folder. 
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This function deletes a folder. 


If the parameter recursive is false, the function will only delete this folder itself in case there is no 
content in this folder. If there is content in this folder, this function will return MSG_ERR_NOT_EMPTY_- 
FOLDER. 


If the parameter recursive is true, regardless of whether content is in this folder, the function will 
recursively delete all its sub folders, messages and this folder itself. 


When deleting a root folder, if the root folder is associated with account(s), the function will not delete the 
root folder and return MSG_ERR_ROOTFOLDER_INUSE. 


Predefined folder except root folder cann’t be deleted individually. Otherwise, MSG_ERR_INVALID_- 
FOLDER_TYPE will be returned. 


Parameters: 
< hConnection is a connection handle. 
— folderId identifies the deleted folder. 


< recursive indicates whether do a recursively deleting operation. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_TYPE Folder type is not valid for this operation. 
MSG_ERR_NOT_EMPTY_FOLDER Folder has content, but deleting operation is not recursive. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 


MSG_ERR_ROOTFOLDER_INUSE The root folder is associated with account(s) and can not be 
deleted. 


MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.6 MSG_ERROR_T MsgGetAllRootFolderlds (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_LIST_S « pFolderIdList) 


Get all root folders. 


This function gets all root folder id list. The parameter pFolderIdList is defined outside this funtion, 
but the memory of its field folderIds is allocated in this function. The function caller should use 
function MsgReleaseFolderIdList to release pFolderIdList memory explicitlly. However if this function is 
failed, the memory is NOT allocated in this function. 
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Parameters: 


— hConnection is a connection handle. 


> pFolderIdList is a pointer to the root folder id list. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.7 MSG_ERROR_T MsgGetFolder (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T folderld, MSG_FOLDER_S xx ppFolderInfo) 


Gets the folder information of the specified folder. 


This function gets all information of the specified folder, which includes common and extended informa- 
tion. For this folder structure may have extended structure, the memory of folder structure is allocated in 
this function. Application MUST release the memory by using function MsgReleaseFolder. However if 
this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— folderId indicates the searched folder id. 


> ppFolderInfo is a pointer to a pointer to all the detail information. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER ppFoldertInfo is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
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MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For releasing folder structure memory, please refer to MsgReleaseFolder 


Since: 


1.0 


6.12.2.8 MSG_ERROR_T MsgGetFolderByType (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T rootFolderId, MSG_FOLDER_TYPE_T folderType, 
MSG_FOLDER_ID_LIST_S x pFolderldList) 


Gets the folder by folder type for the specified root folder. 


This function gets the folder by folder type for the specified root folder. For example, it can retrieve 
inbox/outbox folders of a root folder. The parameter pFolderIdList is defined outside this funtion, 
but the memory of its field folderIds is allocated in this function. The function caller SHOULD use 
function MsgReleaseFolderldList to release pFolderIdList memory explicitlly. However if this function is 
failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— rootFolderld indicates the root folder. 
— folderType indicates the searched folder type. 
> pFolderldList is a pointer to all the returned folder id. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ TYPE Folder type is not valid for this operation. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.12.2.9 MSG ERROR_T MsgGetFolderIdsByStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_T storageld, MSG_FOLDER_ID_LIST_S x 
pFolderIdList) 


Get all the folder id list on a specified storage. 


This function gets all folder id list on a specified storage. The parameter pFolderIdList is defined 
outside this funtion, but the memory of its field folderlIds is allocated in this function. The function 
caller should use function MsgReleaseFolderIdList to release pFolderIdList memory explicitlly. However 
if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— storageld indicates the queried storage. 


> pFolderldList is a pointer to the folder id list. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 

detail error code. 


Since: 


1.0 


6.12.2.10 MSG _ERROR_T MsgGetFolderParentId (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderId, MSG_FOLDER_ID_T x pParentFolderld) 
Gets the parent folder id of a folder. 


This function gets the parent folder id of a folder, and it will return 0 if it is a root folder. 


Parameters: 


— hConnection is a connection handle. 
— folderId indicates the folder id which need to be check. 


— pParentFolderld is a pointer to the returned parent folder id. 


Returns: 


MSG_ERROR_T 
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Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pParentFolderld is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.11 MSG ERROR_T MsgGetPredefinedFolders (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T rootFolderId, MSG_FOLDER_S xx ppInbox, 
MSG_FOLDER S xx ppOutbox, MSG_FOLDER_S ** ppDraft, MSG_FOLDER_S xx 
ppSent, MSG_FOLDER_S xx ppDeleted) 


Gets the predefined folders for the specified root folder. 


This function gets the predefined folders for the specified root folder. The predefined folders include 
inbox/outbox/sent/deleted/draft. If the value of output parameter is NULL, then function will not return 
that predefined folder information. For example, when calling this function peInbox is NULL, then the 
function will not return Inbox predefined folder information. The memory of folder structure is allocated 
in this function. This function caller SHOULD use function MsgReleaseFolder to release the memory. 
However if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— rootFolderld indicates the searched root folder. 
— ppInbox returns the Inbox predefined folder information. 
— ppOutbox returns the Outbox predefined folder information. 
— ppDraft returns the Draft predefined folder information. 
=> ppSent returns the Sent predefined folder information. 


> ppDeleted returns the Deleted predefined folder information. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
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MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.12 MSG ERROR_T MsgMoveFolderToFolder (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderId, MSG_FOLDER_ID_T destFolderld) 


Moves a folder to the specified folder. 


The function moves folder between folders.It will change the folder’s parent folder to another folder. This 
function only works for user defined folder. The root folder and predefined folders cann’t be changed. 


Parameters: 
— hConnection is a connection handle. 
— folderId indicates the moved folder. 
— destFolderld is the Id of the destination folder. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 


MSG_ERR_INVALID_FOLDER_ID folderidordestFolderIdis invalid; destFolderld 
is the subfolder of folder Id; the folder type of moved folder is predefined. 


MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 


detail error code. 
Since: 


1.0 


6.12.2.13 MSG_ERROR_T MsgMoveFolderToStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderld, MSG_STORAGE_ID_T destStorageld) 
Moves a folder to another storage. 


The function moves a folder between storage. All the folder types, root folder, predefined folder, user 
defined folder, can be moved between different storage. 
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Parameters: 
< hConnection is a connection handle. 
— folderId indicates the moved folder. 


— destStorageld is the Id of the destination storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID FOLDER id is invalid. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 

MSG_ERR_STORAGE_ERROR File system error. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.12.2.14 MSG ERROR_T MsgQueryFolder (MSG_CONNECTION_HANDLE_T Connection, 
MSG_FOLDER_ID_T folderld, int iBeginPos, int iCount, MSG_FOLDER_ID_LIST_S « 
pFolderIdList) 


Queries sub folder ids under the specified folder. 


This function queries all the sub folder id list of the specified folder, which it only search the direct children 
of this folder and do not recursively search all the sub folders. The parameter pFolderIdList is defined 
outside this funtion, but the memory of its field folderTds is allocated in this function. The function 
caller SHOULD use function MsgReleaseFolderIdList to release folderIds memory explicitlly. How- 
ever if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— folderId indicates the specific folder which is needed to query. 


< iBeginPos is the index of the result set which satisfies the search condition. If iBeginPos is nega- 
tive, the index begins from 0. 


<— ¡Count is the maximum number of folder information the caller wishes to receive. If ¡Count is 
negative, the method will get all satisfied folders. 


> pFolderIdList is a pointer to the returned folder id list. 
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Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For sample code, please refer to Folder Storage: Querying Folders 


Since: 


1.0 


6.12.2.15 MSG ERROR_T MsgQueryFolderRecursive (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T folderld, int iBeginPos, int iCount, 
MSG_FOLDER_ID_LIST_S « pFolderldList) 


Recursively queries sub folder ids under the specified folder. 


This function queries all the sub folder id list of the specified folder, which it recursively search all the 
sub folders. The parameter pFolderIdList is defined outside this funtion, but the memory of its 
field folderlds is allocated in this function. The function caller SHOULD use function MsgRelease- 
FolderlIdList to release pFolderIdList memory explicitlly. However if this function is failed, the memory is 
NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— folderId indicates the specific folder which is needed to query. 


<— iBeginPos is the index of the resultset which satisfies the search condition. If iBeginPos is negative, 
the index begins from 0. 


<— ¡Count is the maximum number of folder information the caller wishes to receive. If ¡Count is 
negative, this method will get all satisfied folders. 


> pFolderIdList is a pointer to the returned folder id list. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pFolderlIdList is NULL. 
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MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


For sample code, please refer to Folder Storage: Querying Folders 


Since: 


1.0 


6.12.2.16 void MsgReleaseFolder (MSG_FOLDER_S + pFolderInfo) 


Releases a memory block of a folder structure. 
This function releases a memory of folder structure, which is allocated by function MsgGetFolder . 


If pFolderInfo is NULL, nothing happens. If pFolderInfo is invalid, undefined behavior. 


Parameters: 


— pFolderInfo is a pointer to the folder memory block. 


Since: 


1.0 


6.12.2.17 void MsgReleaseFolderIdList (MSG_FOLDER_ID_LIST_S x pFolderIdList) 


Releases a memory block of folder id list. 


This function frees the memory of pointer folderIds inside MSG_FOLDER_ID_LIST_S. If 
pFolderldList or pFolderIdList->folderlds is NULL, nothing happens. If pFolderIdList or pFolderIdList- 
>folderlds is invalid, undefined behavior. 


Note: 


This function does NOT free this structure itself. 


Parameters: 


— pFolderldList is a pointer to the folder id list. 


Since: 


1.0 
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6.12.2.18 MSG _ERROR_T MsgUpdateFolder (MSG_CONNECTION_HANDLE_T hConnection, 
const MSG_FOLDER _S + pFolder) 


Updates a folder. 


This function updates a folder. The data fields, except for folderId, parentId, storageld, folderType, can be 
updated. Following fields of folder structure MUST be valid, otherwise the function will be failed: 


folderlId, parentId, storageld, folderType. 
If the sortType is invalid, the default value MSG_SORT_BY_UNKNOWN will be set. 


Parameters: 


— hConnection is a connection handle. 


— pFolder is a pointer to a structure which contains all updated information. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pFolder is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER The value of mandatory fields except folderld are invalid. 
MSG_ERR_INVALID_FOLDER_ID This folder id doesn’t exist in storage. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.13 Msg Mapi_Storage_Manager.h File Reference 


6.13.1 Detailed Description 


Defines storage management functions in MAPI. 
These functions can be divided into three categories: 
The first is about connection operations. 

The second is about storage registry operations. 

The third is about query and sort operations. 

Sample code:Storage General: Initializing Storage 
#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Storage_Registry.h" 


#include "Msg_Mapi_QueryRule.h" 


Typedefs 


e typedef struct MessagingConnection x MSG_CONNECTION_HANDLE_T 


Defines a Connection handle. 


Functions 


e MSG_ERROR_T MsgCreateStoConnection (MSG_CONNECTION_HANDLE_T xhConnection) 


Creates a Connection handle. 


MSG_ERROR_T MsgDestroyStoConnection (MSG_CONNECTION_HANDLE_T hConnection) 


Destroys the Connection handle. 


MSG_ERROR_T MsgOpenStoConnection (MSG_CONNECTION_HANDLE_T hConnection) 


Opens a connection between application(client) and messaging framework(server). 


MSG_ERROR_T MsgCloseStoConnection (MSG_CONNECTION_HANDLE_T hConnection) 


Closes a connection between application(client) and messaging framework(server). 


MSG_ERROR_T MsglnitStorage () 


Initializes the storages. 


MSG_ERROR_T MsgListStorageRegistry (MSG CONNECTION _HANDLE_T hConnection, 
MSG_STORAGE_ID_LIST_S x*pStorageldList) 


Returns all registered storage ids. 


void MsgReleaseStorageldList (MSG_STORAGE_ID_LIST_S xpStorageldList) 


Releases the memory of storage Id List. 


MSG_ERROR_T MsgGetStorageRegistry (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_STORAGE_ID_T storageld, MSG_STORAGE_REGISTRY_S **ppStorageRegInfo) 
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Gets a storage from registry by storage id. 


MSG_ERROR_T MsgGetMediaTypeByStorageld (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_STORAGE_ID_T storageld, MSG_MEDIA_TYPE_T xpMediaType) 


Gets a media type from registry by storage id. 


void MsgReleaseStorageRegistry (MSG_STORAGE_REGISTRY_S «pStorageRegInfo) 
Releases the memory of MSG_STORAGE_REGISTER_INFO_S structure. 


MSG_ERROR_T MsgListSortType (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
SORT_TYPE_LIST_S x*pSortTypeList) 


Gets a sort type list from configuration files. 


void MsgReleaseSortTypeList (MSG_SORT_TYPE_LIST_S *pSortTypeList) 


Releases the memory of sort type list. 


MSG_ERROR_T MsgListQueryId (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
QUERY_ID_LIST_S xpQuerylIdList) 


Gets a query Id list from configuration files. 


void MsgReleaseQueryIdList (MSG_QUERY_ID_LIST_S *pQuerylIdList) 
Releases the memory of query Id list. 


MSG_ERROR_T MsgGetFwStorageStatus (MSG_STORAGE _ID_T storageld, unsigned long long 
*totalSize, unsigned long long *usedSize, MSG_SIZE_UNIT_T xunit) 


Gets framework storage status by storage id. 


MSG_ERROR_T MsgGetMsgStorageStatus (MSG_STORAGE_ID_T storageld, const MSG_- 
MESSAGE_TYPE_S *msgType, unsigned long long xtotalSize, unsigned long long x*usedSize, 
MSG_SIZE_UNIT_T xunit) 


Gets specific message storage status by storage id and message type. 


MSG_PLUGIN_ERROR_T MsgGetStoragePluginError (MSG_CONNECTION_HANDLE_T 
hConnection) 


Get storage specific plugin error. 


6.13.2 Typedef Documentation 
6.13.2.1 typedef struct MessagingComnection* MSG_CONNECTION_HANDLE_T 


Defines a Connection handle. 


For details of Connection, please refer to Connection 


6.13.3 Function Documentation 


6.13.3.1 MSG_ERROR_T MsgCloseStoConnection (MSG_CONNECTION_HANDLE_T 
hConnection) 


Closes a connection between application(client) and messaging framework(server). 
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When this function returns successfully, the communication between the application and messaging frame- 
work will be unavailable. 


If hConnection is NULL, this function does nothing and returns MSG_ERR_INVALID_CONNECTION. 


For details of Connection, please refer to Connection 


Parameters: 


— hConnection is a Connection handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 


Please refer to Storage General: Initializing Storage 


Since: 


1.0 


6.13.3.2 MSG_ERROR_T MsgCreateStoConnection (MSG_CONNECTION_HANDLE_T x 
hConnection) 
Creates a Connection handle. 


This is the only way for applications to get a Connection handle. Such operations as adding, deleting and 
updating must be bound with a connection handle. 


For details of Connection, please refer to Connection 


Parameters: 


— hConnection is a pointer to a Connection handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER Pointer is NULL. 
MSG_ERR_MEMORY_ERROR memory is error. 


Please refer to Storage General: Initializing Storage. 


Since: 


1.0 
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6.13.3.3  MSG_ERROR_T MsgDestroyStoConnection (MSG_CONNECTION_HANDLE_T 
hConnection) 


Destroys the Connection handle. 


After the Connection is destroyed, it can not be used any more. For each created Connection, please make 
sure that it should be destroyed when it’s not used any more. If the input parameter is NULL, this function 
does nothing and returns MSG_ERR_INVALID_CONNECTION. 


For details of Connection, please refer to Connection 


Parameters: 


— hConnection is a Connection handle. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 


Since: 


1.0 


6.13.3.4 MSG _ERROR_T MsgGetFwStorageStatus (MSG_STORAGE_ID_T storageld, unsigned 
long long x totalSize, unsigned long long x usedSize, MSG_SIZE_UNIT_T + unit) 


Gets framework storage status by storage id. 


This function is to get total size and used size of the specified framework storage. 


Parameters: 
— storageld is an integer value indicating which storage. 
— totalSize the total size in this storage. 
— usedSize used size in this storage. 


— unit the unit of the size. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER totalSize is NULL or usedSize is NULL or unit is NULL. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
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MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.13.3.5 MSG_ERROR_T MsgGetMediaTypeByStorageld (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_T storageld, MSG_MEDIA_TYPE_T x pMediaType) 


Gets a media type from registry by storage id. 


Parameters: 
— hConnection is a Connection handle. 
— storageld is an integer value indicating which storage. 


— pMediaType is an enumeration value indicating which media . 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMediaType is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.13.3.6 MSG_ERROR_T MsgGetMsgStorageStatus (MSG_STORAGE_ID_T storageld, const 
MSG_MESSAGE_TYPE S « msgType, unsigned long long + totalSize, unsigned long long 
x usedSize, MSG_SIZE_UNIT_T x unit) 


Gets specific message storage status by storage id and message type. 


This function is to get total size and used size of the specified message storage. 


Parameters: 
— storageld is an integer value indicating which storage. 
— msgType is the specific message type 
> totalSize the total size in this storage. 


> usedSize used size in this storage. 
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— unit the unit of the size. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 


MSG_ERR_NULL_POINTER msgType is NULL or totalSize is NULL or usedSize is 
NULL or unit is NULL. 


MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 
Since: 


1.0 


6.13.3.7 MSG_PLUGIN_ERROR_T MsgGetStoragePluginError (MSG_CONNECTION_- 
HANDLE_T hConnection) 
Get storage specific plugin error. 


This function is to get the specific plugin error. In case that some functions return MSG_ERR_PLUGIN, 
applications can call this function immediately to get specific error code of the plugins. If hConnection is 
invalid, this function will return 0. 


Parameters: 


— hConnection is a pointer to an established connection handle. 


Returns: 


MSG_PLUGIN_ERROR_T 


6.13.3.8 MSG_ERROR_T MsgGetStorageRegistry (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_T storageld, MSG_STORAGE_REGISTRY_S xx 
ppStorageRegInfo) 


Gets a storage from registry by storage id. 

This function allocates the memory of MSG_STORAGE_REGISTRY_S structure. Applications need to 
call MsgReleaseStorageRegistry to release the memory after using the structure. 

Parameters: 


— hConnection is a Connection handle. 
— storageld is an integer value indicating which storage. 


> ppStorageRegInfo is a pointer to a struct pointer . 
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Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER ppStorageRegInfo is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.13.3.9 MSG _ERROR_T MsgInitStorage () 


Initializes the storages. 

If there is data in storage, all the data will be cleaned up and reset with default values, If there is no data in 
storage, all the data will be created and set with default values. 

Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_STORAGE_ERROR Storage error. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.13.3.10 MSG ERROR_T MsgListQueryId (MSG_CONNECTION_HANDLE_T Connection, 
MSG_QUERY_ID_LIST_S x pQueryldList) 
Gets a query Id list from configuration files. 


Applications need to call MsgReleaseQueryldList to release the memory of querylds in the structure. 


Parameters: 


— hConnection is a Connection handle. 
— pQueryldList is a pointer to a MSG_QUERY_ID_LIST _S struct . 
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Returns: 


MSG_ERROR_T 
Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pQuerylIdList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.13.3.11 MSG _ERROR_T MsgListSortType (MSG_CONNECTION_HANDLE_T Connection, 
MSG_SORT_TYPE_LIST_S + pSortTypeList) 


Gets a sort type list from configuration files. 
Applications need to call MsgReleaseSortTypeList to release the memory of sortTypes in the structure. 
Parameters: 


— hConnection is a Connection handle. 
> pSortTypeList is a pointer to a MSG_SORT_TYPE_LIST_S structure . 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pSortTypeList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.13.3.12 MSG_ERROR_T MsgListStorageRegistry (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_LIST_S x pStorageldList) 

Returns all registered storage ids. 

Applications need to allocate the structure pStorageldList. 


When this function returns successfully, the registered storage ids will be filled in pStorageldList- 
>pStoragelds. Applications need to call MsgReleaseStorageldList to release the memory of 
pStorageldList->pStoragelds. 
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Parameters: 


— hConnection is a Connection handle. 


> pStorageldList is a pointer to an MSG_STORAGE_ID_LIST_S structure.Indicate which storages 
will be supported. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pStorageldList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


Since: 


1.0 


6.13.3.13 MSG _ERROR_T MsgOpenStoConnection (MSG_CONNECTION_HANDLE_T 
hConnection) 
Opens a connection between application(client) and messaging framework(server). 


When this function returns successfully, applications can do the operations such as adding, deleting and 
updating etc. 


For details of Connection, please refer to Connection 


Parameters: 


— hConnection is a pointer to a Connection handle. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 


Please refer to Storage General: Initializing Storage 


Since: 


1.0 
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6.13.3.14 void MsgReleaseQueryIdList (MSG_QUERY_ID_LIST_S x pQueryIdList) 


Releases the memory of query Id list. 


This function releases the memory of queryIds in MSG_QUERY_ID_LIST_S structure. If pQueryIdList 
or pQueryIdList->queryIds is NULL, nothing happens. If pQueryIdList or pQueryIdList->querylds is 
invalid, undefined behavior. 


Note: 


This function only frees the list member inside the structure. It doesn’t free the structure itself. 


Parameters: 


— pQueryldList is a pointer to an MSG_QUERY_ID_LIST_S structure. 


Since: 


1.0 


6.13.3.15 void MsgReleaseSortTypeList (MSG_SORT_TYPE_LIST_S + pSortTypeList) 


Releases the memory of sort type list. 


This function releases the memory of sortTypes in MSG_SORT_TYPE_LIST_S structure. 


If pSortTypeList or pSortTypeList->sortTypes is NULL, nothing happens. If pSortTypeList or 
pSortTypeList->sortTypes is invalid, undefined behavior. 


Note: 


This function only frees the list member inside the structure. It doesn’t free the structure itself. 


Parameters: 


— pSortTypeList is a pointer to an MSG_SORT_TYPE_LIST_S structure. 


Since: 


1.0 


6.13.3.16 void MsgReleaseStorageIdList (MSG_STORAGE _ID_LIST_S « pStorageldList) 


Releases the memory of storage Id List. 

This function releases the memory of pStorageIds in MSG_STORAGE_ID_LIST_S structure. 

If pStorageldList or pStorageldList->pStoragelds is NULL, nothing happens. If pStorageldList or 
pStorageldList- >pStoragelds is invalid, undefined behavior. 

Note: 


This function only frees the list pointer member inside the structure. It doesn't free the structure itself. 


Parameters: 


— pStorageldList is a pointer to an MSG_STORAGE_ID_LIST_S structure.Indicate which storages 
will be released. 
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Since: 


1.0 


6.13.3.17 void MsgReleaseStorageRegistry (MSG_STORAGE_ REGISTRY _S x pStorageRegInfo) 


Releases the memory of MSG_STORAGE_REGISTER_INFO_S structure. 
If pStorageRegInfo is NULL, nothing happens. If pStorageRegInfo is invalid, undefined behavior. 


Parameters: 


— pStorageRegInfo is a pointer to an MSG_STORAGE_REGISTRY_S structure. 


Since: 


1.0 
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6.14 Msg Mapi_Storage_Message.h File Reference 


6.14.1 Detailed Description 


Defines message storage related functions in MAPI. 


The file includes all message storage functions, such as adding, updating, deleting etc. 


#include "Msg_Mapi_Types.h" 


#include "Msg_Mapi_Message.h" 


#include "Msg_Mapi_Storage_Manager.h" 


#include "Msg_Mapi_QueryRule.h" 


Functions 


MSG_ERROR_T MsgAddMessage (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
MESSAGE S xpMsg) 


Adds a message into storage. 


MSG_ERROR_T MsgUpdateMessage (MSG_CONNECTION_HANDLE_T hConnection, const 
MSG_MESSAGE_S xpMsg) 


Updates a message in storage. 


MSG_ERROR_T MsgDeleteMessage (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
MESSAGE_ID_T Msgld) 


Deletes a message by message idn. 


MSG_ERROR_T MsgDeleteAllMessagelnFolder (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_FOLDER_ID_T Folderld) 


Deletes all messages in the specified folder. 


MSG_ERROR_T MsgMoveMessageToFolder (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_MESSAGE_ID_T Msgld, MSG_FOLDER_ID_T DesFolderld) 


Moves a message to the specified folder. 


MSG_ERROR_T MsgMoveMessageToStorage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_MESSAGE_ID_T Msgld, MSG_STORAGE_ID_T DestStorageld) 


Moves a message to another storage. 


MSG_ERROR_T MsgCountMessage (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S x*pMsgType, int *pCount) 


Gets the number of messages under the specified folder by message type. 


MSG_ERROR_T MsgCountMessageRecursive (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S x*pMsgType, int *pCount) 


Gets the number of messages, both directly and indirectly, under the specified folder by message type. 


MSG_ERROR_T MsgCountUnreadMessage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S *pMsgType, int *pCount) 


Gets the number of unread messages under the specified folder by message type. 
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MSG_ERROR_T MsgCountUnreadMessageRecursive (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S *pMsgType, int 
*pCount) 


Gets the number of unread messages, both directly and indirectly, under the specified folder by message 


type. 


MSG_ERROR_T MsgQueryMessage (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
FOLDER_ID_T Folderld, int iBeginIndex, int iCount, const MSG_SORT_RULE_S xpSortRule, 
const MSG_QUERY_LIST_S *pQueryList, MSG_MESSAGE_ID_LIST_S *pMsglIdList) 


Gets the matched message ids under the specified folder. 


MSG_ERROR_T MsgQueryMessageRecursive (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_FOLDER_ID_T Folderld, int iBeginIndex, int iCount, const MSG_SORT_- 
RULE_S x*pSortRule, const MSG_QUERY_LIST_S *pQueryList, MSG_MESSAGE ID _LIST_S 
*pMsgldList) 


Gets the matched message ids, both directly and indirectly, under the specified folder. 
MSG_ERROR_T MsgGetMessage (MSG_CONNECTION_HANDLE_T hConnection, MSG_- 
MESSAGE_ID_T Msgld, MSG_MESSAGE_S x**ppMsg) 

Returns the message detail information. 
MSG_ERROR_T MsgGetMessageCommInfo (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_MESSAGE_ID_T Msgld, MSG_MESSAGE_S xxppMsg) 

Returns the message common information. 
MSG_ERROR_T MsgGetMessageParentld (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_MESSAGE_ID_T Msgld, MSG_FOLDER_ID_T xpParentFolderld) 


Returns the folder id in which the message located. 


void MsgReleaseMessage (MSG_MESSAGE_S xpMsg) 
Frees the memory of MSG_MESSAGE_S allocated in MsgGetMessage If pMsg is NULL, nothing happens. 
If pMsg is invalid, undefined behavior. 
void MsgReleaseMessageCommInfo (MSG_MESSAGE_S «pMsg) 
Frees the memory of MSG_MESSAGE_S allocated in MsgGetMessageComminfo If pMsg is NULL, nothing 
happens. If pMsg is invalid, undefined behavior. 
void MsgReleaseMessageldList (MSG_MESSAGE _ID_LIST_S xpMsgldList) 
Frees the memory of pointer inside MSG_MESSAGE_ID_LIST_S allocated in MsgQueryMessage, Msg- 
QueryMessageRecursive and MsgGetMessageldsByStorage. 
MSG_ERROR_T MsgGetMessageldsByStorage (MSG_CONNECTION_HANDLE_T hConnec- 
tion, MSG_STORAGE_ID_T Storageld, MSG_MESSAGE_ID_LIST_S *pMsglds) 


Returns the message Ids by storage Id. 
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6.14.2 Function Documentation 


6.14.2.1 MSG ERROR_T MsgAddMessage (MSG_CONNECTION_HANDLE_T Connection, 
MSG_MESSAGE S « pMsg) 


Adds a message into storage. 


Mandatory fields of message structure MUST be valid, otherwise the function will be failed. The manda- 
tory fields for adding operation are parent Id, msgType, storageld. 


If storageId is MSG STORAGE DEFAULT, the message will be added to the 
defaultMsgStorageld in its associated account. 


Parameters: 


— hConnection is a connection handle. 


> pMsg is a pointer to a MSG_MESSAGE, S structure. pMsg->msgld will be set to a valid value in 
storage when this function is returned successfully. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsg is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE Mandatory fields of message are invalid. 
MSG_ERR_STORAGE_FULL Storage is FULL. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX_NUMBER_REACHED max number reached 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Please refer to Message Storage: Creating and Storing a Message. 


Since: 


1.0 


6.14.2.2 MSG_ERROR_T MsgCountMessage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S x pMsgType, int « 
pCount) 


Gets the number of messages under the specified folder by message type. 


Note: 


If pMsgType is NULL, it will return the messages number of all the message types. 
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Parameters: 
— hConnection is a connection handle. 
— Folderld is a 1d of folder to be counted. 
— pMsgType is a pointer to MSG_MESSAGE_TYPE_S structure. 


— pCount is a integer pointer. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.14.2.3 MSG _ERROR_T MsgCountMessageRecursive (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T Folderld, const MSG_MESSAGE_TYPE_S x 
pMsgType, int x pCount) 


Gets the number of messages, both directly and indirectly, under the specified folder by message type. 


Note: 


If pMsgType is NULL, it will return the messages number of all the message types. 


Parameters: 


— hConnection is a connection handle. 
— Folderld is querying folder Id. 
— pMsgType is a pointer to MSG_MESSAGE_TYPE_S structure. 


— pCount is an integer pointer. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
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MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 
Since: 


1.0 


6.14.2.4 MSG ERROR_T MsgCountUnreadMessage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T FolderId, const MSG_MESSAGE_TYPE_S x 
pMsgType, int x pCount) 


Gets the number of unread messages under the specified folder by message type. 


Note: 


If pMsgType is NULL, it will return the messages number of all the message types. 


Parameters: 


— hConnection is a connection handle. 
— Folderld is querying folder Id. 
— pMsgType is a pointer to MSG_MESSAGE_TYPE_S structure. 


— pCount is an integer pointer. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pCount is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.14.2.5 MSG _ERROR_T MsgCountUnreadMessageRecursive (MSG_CONNECTION_- 
HANDLE_T hConnection, MSG_FOLDER_ID_T Folderld, const 
MSG_MESSAGE_TYPE S x pMsgType, int x pCount) 


Gets the number of unread messages, both directly and indirectly, under the specified folder by message 
type. 


Note: 


If pMsgType is NULL, it will return the messages number of all the message types. 


Parameters: 
— hConnection is a connection handle. 
— Folderld is a querying folder Id. 
— pMsgType is a pointer to MSG_MESSAGE_TYPE_S structure. 


— pCount is an integer pointer. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pCount is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 
Since: 


1.0 


6.14.2.6 MSG _ERROR_T MsgDeleteAllMessageInFolder (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T Folderld) 

Deletes all messages in the specified folder. 

This function is to delete all messages in the specified folder,but it is not to delete the specified folder’s 

subfolders and the messages in the subfolders. 

Parameters: 


— hConnection is a connection handle. 
— Folderld is a folder Id. 
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Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.14.2.7 MSG _ERROR_T MsgDeleteMessage (MSG_CONNECTION_HANDLE_T hConnection, 
MSG_MESSAGE_ID_T Msgld) 


Deletes a message by message idn. 


Parameters: 
— hConnection is a connection handle. 


— Msgld indicates to be deleted message’s Id. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.14.2.8 MSG_ERROR_T MsgGetMessage (MSG_CONNECTION_HANDLE_T Connection, 
MSG_MESSAGE_ID_T Msgld, MSG_MESSAGE S xx ppMsg) 
Returns the message detail information. 


This function returns the message detail information including both common extension data 
(pCommExtData) and specific message extension data (pExtData). 


Note: 


Message memory will be allocated inside this function. Applications need to call MsgReleaseMessage 
to free the memory. However if this function is failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— Msgld indicates to be returned messages Id. 


— ppMsg is a pointer to a message pointer. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER ppMsg is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Please refer to Message Storage: Retrieving Message List and Entity. 


Since: 


1.0 


6.14.2.9 MSG_ERROR_T MsgGetMessageCommInfo (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_MESSAGE_ID_T Msgld, MSG_MESSAGE S xx ppMsg) 

Returns the message common information. 

This function returns the message common information including common extension data (pCommExt- 

Data) without specific message extension data (pExtData). 

Note: 


Message memory will be allocated inside this function. Applications need to call MsgReleaseMes- 
sageCommInfo to free the memory. However if this function is failed, the memory is NOT allocated 
in this function. 
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Parameters: 
< hConnection is a connection handle. 
— Msgld indicates to be returned message’s Id. 


=> ppMsg is a pointer to a message pointer. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER ppMsg is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 

MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 


detail error code. 
Since: 


1.0 


6.14.2.10 MSG ERROR_T MsgGetMessageldsByStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_STORAGE_ID_T Storageld, MSG_MESSAGE_ID_LIST $ x 
pMsglds) 

Returns the message Ids by storage Id. 

Applications need to allocate the structure pMsgIds. 


When this function returns successfully, the storage ids will be filled in pMsglds->msglds. Applications 
need to call MsgReleaseMessageldList to release the memory of pMsglds->msglds. However if this func- 
tion is failed, the memory is NOT allocated in this function. 


Parameters: 


< hConnection is a connection handle. 
— Storageld is querying storage Id. 
— pMsglds is a pointer to a MSG_MESSAGE_ID_LIST_S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pMsglds is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
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MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_STORAGE Message id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.14.2.11 MSG ERROR_T MsgGetMessageParentId (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_MESSAGE_ID_T Msgld, MSG_FOLDER_ID_T x pParentFolderld) 


Returns the folder id in which the message located. 


Parameters: 
— hConnection is a connection handle. 
— Msgld indicates which message should be gotten. 
> pParentFolderld a pointer to the parent folder id. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_NULL_POINTER pParentFolderidis NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID Message id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.14.2.12 MSG ERROR_T MsgMoveMessageToFolder (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_MESSAGE_ID_T MsgId, MSG_FOLDER_ID_T Des FolderId) 


Moves a message to the specified folder. 


The function moves a message between folders. 
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Parameters: 
— hConnection is a connection handle. 
— Msgld is the Id of the message to be moved. 
— DesFolderld is the Id of the destination folder. 


Returns: 


MSG_ERROR_T 


Return values: 
MSG_SUCCESS Succeeds in operation. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 


detail error code. 
Since: 


1.0 


6.14.2.13 MSG_ERROR_T MsgMoveMessageToStorage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_MESSAGE_ID_T Msgld, MSG_STORAGE_ID_T DestStorageld) 


Moves a message to another storage. 


The function moves a message between storages. 


Parameters: 
— hConnection is a connection handle. 
— Msgld is the Id of the message to be moved. 
— DestStorageld is the Id of the destination storage. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid. 
MSG_ERR_INVALID_STORAGE Storage id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
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MSG_ERR_MEMORY_ERROR memory is error. 
MSG_ERR_MAX_ NUMBER_REACHED max number reached 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 


6.14.2.14 MSG ERROR_T MsgQueryMessage (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T Folderld, int iBeginIndex, int iCount, const 
MSG_SORT_RULE_S x pSortRule, const MSG_QUERY_LIST_S x pQueryList, 
MSG_MESSAGE_ID_LIST_S « pMsgldList) 


Gets the matched message ids under the specified folder. 


If pQueryList is NULL,the function will return all message in this folder. If pSortRule is NULL, 
the sort type is depended on underlying storage. 


Note: 


The memory at MSG_MESSAGE_ID_S of MSG_MESSAGE_ID_LIST_S will be allocated inside 
this method, which need be released by calling MsgReleaseMessageldList. However if this function 
1s failed, the memory is NOT allocated in this function. 


Parameters: 


— hConnection is a connection handle. 
— Folderld is querying folder Id. 


— iBeginIndex is an integer value. Indicate start position. If iBeginIndex is negative, index begins 
from 0. 


— ¡Count is the maximum number of message information the caller wishes to receive. If ¡Count is 
negative, this method will get all satisfied messages. 


— pSortRule is a pointer to MSG_SORT_RULE_S structure. Indicate to use which sort rule. 


— pQueryList is a pointer MSG_QUERY_LIST_S structure. Indicate QueryRule,for query rule de- 
scription,refer to MSG_QUERY_LIST_S. 


=> pMsgldList is a pointer to a MSG_MESSAGE_ID_LIST_S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsgldList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
MSG_ERR_INVALID_SORT_TYPE Sort type is invalid. 
MSG_ERR_INVALID_QUERY_ID Query id is invalid. 
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MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Please refer to Message Storage: Retrieving Message List and Entity. 


Since: 


1.0 


6.14.2.15 MSG ERROR_T MsgQueryMessageRecursive (MSG_CONNECTION_HANDLE_T 
hConnection, MSG_FOLDER_ID_T Folderld, int iBeginIndex, int iCount, const 
MSG_SORT_RULE_S =» pSortRule, const MSG_QUERY_LIST_S x pQueryList, 
MSG_MESSAGE_ID_LIST_S « pMsgldList) 


Gets the matched message ids, both directly and indirectly, under the specified folder. 


If pQueryList is NULL,the function will return all message in this folder. If pSortRule is NULL, 
the sort type is depended on underlying storage. 


Note: 


The memory at MSG_MESSAGE_ID_S of MSG_MESSAGE _ID_LIST_S will be allocated inside 
this method, which need be released by calling MsgReleaseMessageldList. However if this function 
1s failed, the memory is NOT allocated in this function. 


Parameters: 
— hConnection is a connection handle. 
— Folderld is querying folder Id. 


<— iBeginIndex is an integer value. Indicate start position. If iBeginIndex is negative, index begins 
from 0. 


— ¡Count is the maximum number of message information the caller wishes to receive. If ¡Count is 
negative, this method will get all satisfied messages. 


— pSortRule is a pointer to MSG_SORT_RULE_S structure. Indicate to use which sort rule. 


— pQueryList is a pointer to MSG_QUERY_LIST_S structure. Indicate QueryRule,for query rule 
description,refer to MSG_QUERY_LIST_S. 


=> pMsgldList is a pointer to a MSG_MESSAGE_ID_LIST_S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsgldList is NULL. 
MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_FOLDER_ID Folder id is invalid. 
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MSG_ERR_INVALID_SORT_TYPE Sort type is invalid. 
MSG_ERR_INVALID_QUERY_ID Query id is invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Please refer to Message Storage: Retrieving Message List and Entity. 


Since: 


1.0 


6.14.2.16 void MsgReleaseMessage (MSG_MESSAGE S + pMsg) 


Frees the memory of MSG_MESSAGE _S allocated in MsgGetMessage If pMsg is NULL, nothing hap- 
pens. If pMsg is invalid, undefined behavior. 
Parameters: 


— pMsg is a pointer to an MSG_MESSAGE S structure. 


Since: 


1.0 


6.14.2.17 void MsgReleaseMessageCommInfo (MSG_MESSAGE S « pMsg) 


Frees the memory of MSG_MESSAGE_S allocated in MsgGetMessageComminfo If pMsg is NULL, noth- 
ing happens. If pMsg is invalid, undefined behavior. 
Parameters: 


— pMsg is a pointer to an MSG_MESSAGE S structure. 


Since: 


1.0 


6.14.2.18 void MsgReleaseMessageldList (MSG_MESSAGE_ID_LIST_S + pMsgldList) 
Frees the memory of pointer inside MSG_MESSAGE_ID_LIST_S allocated in MsgQueryMessage, Msg- 
QueryMessageRecursive and MsgGetMessageldsB yStorage. 


This function releases the memory of msgIds in MSG_MESSAGE_ID_LIST_S structure. If pMsgIdList 
or pMsgldList->msglds is NULL, nothing happens. If pMsgIdList or pMsgldList->msglds is invalid, 
undefined behavior. 


Note: 


This function does not free this sturcture itself. 
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Parameters: 


— pMsgldList is a pointer to an MSG_MESSAGE_ID_LIST_S structure. 


Since: 


1.0 


6.14.2.19 MSG ERROR_T MsgUpdateMessage (MSG_CONNECTION_HANDLE_T 
hConnection, const MSG_MESSAGE S « pMsg) 


Updates a message in storage. 


The function is to update message data for the message indentified by the given msgld as long as the given 
values are valid. 


Following fields of message structure MUST be valid, otherwise the function will be failed. msgla, 
parentId, msgType, storageld. 


Note: 


pMsg->msgId MUST NOT be updated,because pMsg->msgld is a unique Id on platform. 
pMsg->parentId MUST NOT be updated. The function will return MSG_ERR_INVALID_- 
MESSAGE, if inputting a new pMsg->parentld. If applications want to move message between fold- 
ers, applications SHOULD call MsgMoveMessageToFolder. 

pMsg->storageld MUST NOT be updated. The function will return MSG_ERR_INVALID_- 
MESSAGE, if inputting a new pMsg->storageld. If applications want to move message between stor- 
ages, applications SHOULD call MsgMoveMessageToStorage. 


Parameters: 


— hConnection is a connection handle. 


— pMsg is a const pointer to a MSG_MESSAGE S structure. 


Returns: 


MSG_ERROR_T 


Return values: 


MSG_SUCCESS Succeeds in operation. 

MSG_ERR_NULL_POINTER pMsg is NULL. 

MSG_ERR_INVALID_CONNECTION Connection is invalid. 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected. 
MSG_ERR_INVALID_MESSAGE Mandatory fields of message are invalid. 
MSG_ERR_COMMUNICATION_ERROR communication between client and server is error. 
MSG_ERR_MEMORY_ERROR memory is error. 


MSG_ERR_PLUGIN the generic error code for plugin. Call MsgGetStoragePluginError() to get 
detail error code. 


Since: 


1.0 
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6.15 Msg Mapi_Storage_Registry.h File Reference 


6.15.1 Detailed Description 


Defines the storage registry structure. 


#include "Msg_Mapi_Types.h" 


#include <stdlib.h> 


Data Structures 


e struct MSG STORAGE REGISTRY_S 


Represents a storage registry entry. 


Typedefs 


e typedef struct _MSG_ STORAGE _REGISTRY_S MSG_STORAGE_REGISTRY_S 


6.15.2 Typedef Documentation 


6.15.2.1 typedef struct MSG STORAGE_REGISTRY_S MSG_STORAGE_ REGISTRY_S 
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6.16 Msg Mapi_Types.h File Reference 
6.16.1 Detailed Description 


Defines general types. 


Data Structures 


e struct _MSG MESSAGE TYPE_S 


Represents a message type. 


struct MSG MESSAGE TYPE_LIST_S 


Represents a message types list. 


struct MSG_STORAGE ID_LIST_S 


Represents a storage id list. 


struct_MSG_STRING_S 


Represents a string. 


struct MSG MESSAGE ID LIST_S 


Represents a message id list. 


struct _MSG_FOLDER_ID_LIST_S 


Represents a folder id list. 


struct _MSG_ACCOUNT_ID_LIST_S 


Represents an account id list. 


Defines 


e #define bool unsigned char 


Defines bool type. 


e #define true 1 


Defines true value. 


» #define false O 


Defines false value. 


e #define MSG_INVALID_MESSAGE_ID Oxffffffff 


Defines invalid id for message. 


e #define MSG_INVALID_ACCOUNT_ID Oxffff 


Defines invalid id for account. 


e #define MSG_INVALID_FOLDER_ID Oxffff 
Defines invalid id for folder. 
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e #define MSG_DEFAULT_ACCOUNT_ID 0 


Defines default account id. 


e #define MSG_DEFAULT_FOLDER_ID 0 
Defines default folder id. 


e #define MSG_ERROR_BEGIN (-255) 


Defines begin value for error. 


Typedefs 


e typedef int MSG_MAIN_TYPE_T 


Represents a message main type. 


typedef int MSG_SUB_TYPE_T 


Represents a message sub type. 


typedef struct_MSG_MESSAGE_TYPE_S MSG_MESSAGE_TYPE_S 
typedef struct _MSG_MESSAGE_TYPE_LIST_S MSG_MESSAGE_TYPE_LIST_S 
typedef int MSG_ERROR_T 


Represents an error code. 


typedef unsigned int MSG_PLUGIN_ERROR_T 


Error code specific for plugins. 


typedef int MSG_SESSION_PRIORITY_T 


Represents a session priority. 


typedef int MSG_MESSAGE_PRIORITY_T 


Represents a message priority. 


typedef int MSG_STATUS_T 


Represents a status. 


typedef int MSG_REQUEST_TYPE_T 


Represents a request type. 


typedef unsigned int MSG_REQUEST_ID_T 


Represents a request id, which is unique for each request. 


typedef unsigned int MSG_STORAGE_ID_T 


Represents a Storage id. 


typedef unsigned int MSG_MEDIA_TYPE_T 


Represents a media type. 


typedef unsigned int MSG_FOLDER_TYPE_T 
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Represents a folder type. 


typedef struct_MSG_ STORAGE _ID_LIST_S MSG_STORAGE ID_LIST_S 
typedef int MSG_CONTACT_TYPE_T 


Represents a contact type. 


typedef int MSG_ENCODE_TYPE_T 


Represents an encoding type. 


typedef struct_MSG_STRING_S MSG_STRING_S 
typedef unsigned long MSG_MESSAGE_ID_T 


Represents a messsage id. 


typedef unsigned int MSG_FOLDER_ID_T 


Represents a folder id. 


typedef unsigned int MSG_ACCOUNT_ID_T 


Represents an account id. 


typedef struct_MSG_MESSAGE_ID_LIST_S MSG_MESSAGE ID_LIST_S 
typedef struct _MSG_FOLDER_ID_LIST_S MSG_FOLDER_ID_LIST_S 
typedef struct _MSG_ACCOUNT_ID_LIST_S MSG_ACCOUNT_ID_LIST_S 
typedef int MSG_SIZE_UNIT_T 


Represents the unit of the size. 


Enumerations 


e enum_MSG_MAIN_TYPE E { 


MSG_MESSAGE_TYPE_UNKNOWN, MSG_MESSAGE_TYPE_MMS, MSG_MESSAGE - 
TYPE_EMAIL, MSG_MESSAGE_TYPE_SMS, 


MSG_MESSAGE_TYPE_IMODE } 


Represents the values of message main types. 


enum _MSG_ERROR_E { 


MSG_SUCCESS = 0, MSG_ERR_FS_ERROR = MSG_ERROR_ BEGIN - 1, MSG_ERR_FS_- 
FULL = MSG_ERROR_BEGIN - 2, MSG_ERR_INVALID_STORAGE = MSG_ERROR_BEGIN 
s3; 


MSG_ERR_INVALID_MSG_TYPE = MSG_ERROR_BEGIN - 4, MSG_ERR_INVALID_SORT_- 
TYPE = MSG_ERROR_BEGIN - 5, MSG_ERR_INVALID_FOLDER_ID = MSG_ERROR - 
BEGIN - 6, MSG_ERR_INVALID_STORAGE_REG = MSG_ERROR_BEGIN - 7, 


MSG_ERR_INVALID_CONNECTION = MSG_ERROR_BEGIN - 8, MSG _ERR_NULL_- 
POINTER = MSG_ERROR_ BEGIN - 9, MSG_ERR_INVALID_MESSAGE_ ID =MSG_ERROR - 
BEGIN - 10, MSG_ERR_INVALID_ACCOUNT_ID = MSG_ERROR_ BEGIN - 11, 


MSG_ERR_INVALID_QUERY_ID = MSG_ERROR_ BEGIN - 12, MSG_ERR_SESSION_NOT_- 
CONNECTED = MSG_ERROR_BEGIN - 13, MSG_ERR_INVALID_SESSION_HANDLE = 
MSG_ERROR_BEGIN - 14, MSG_ERR_PERMISSION_DENIED = MSG_ERROR_BEGIN - 15, 
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MSG_ERR_STORAGE_NOT_INIT = MSG_ERROR_BEGIN - 16, MSG_ERR_ STORAGE _- 
REG_NOT_INIT = MSG_ERROR_BEGIN - 17, MSG_ERR_INVALID_SESSION_PRIORITY = 
MSG_ERROR_BEGIN - 18, MSG_ERR_INVALID_FILTER_ID = MSG_ERROR_BEGIN - 19, 


MSG_ERR_INVALID_REQUEST = MSG_ERROR_BEGIN - 20, MSG_ERR_INVALID_- 
FOLDER_TYPE = MSG_ERROR_BEGIN - 21, MSG_ERR_ INVALID FOLDER = MSG _- 
ERROR_BEGIN - 22, MSG_ERR_NOT_EMPTY_FOLDER = MSG_ERROR_BEGIN - 23, 


MSG_ERR_INVALID_ACCOUNT = MSG_ERROR_BEGIN - 24, MSG_ERR_CONNECTION_- 
NOT_CONNECT = MSG_ERROR_BEGIN - 25, MSG_ERR_ INVALID MESSAGE = MSG_- 
ERROR_BEGIN - 26, MSG_ERR_STORAGE_ FULL = MSG_ERROR_BEGIN - 27, 


MSG_ERR_ROOTFOLDER_INUSE = MSG_ERROR_BEGIN - 28, MSG_ERR_ STORAGE _- 
ERROR = MSG_ERROR_BEGIN - 29, MSG_ERR_MEMORY_ERROR = MSG_ERROR_BEGIN 
- 30, MSG_ERR_COMMUNICATION_ERROR = MSG_ERROR_BEGIN - 31, 


MSG_ERR_ MAX NUMBER REACHED = MSG _ERROR BEGIN - 32, MSG_ERR - 
INVALID_REQUEST_ID = MSG_ERROR_BEGIN - 33, MSG_ERR_ UNKNOWN = MSG _- 
ERROR_BEGIN - 0x00008000, MSG_ERR_ FRAMEWORK RESERVE BEGIN = MSG_- 
ERROR_BEGIN - 0x00010000, 


MSG_ERR_FRAMEWORK_RESERVE_END = MSG_ERROR_BEGIN - 0x00020000, MSG_- 
ERR_PLUGIN = MSG_ERROR_BEGIN - 0x08000000, MSG_ERR_PLUGIN_DEF_BEGIN_- 
VALUE = MSG_ERR_PLUGIN } 


Represents the values of error codes. 


enum _MSG_SESSION_PRIORITY_E { 


MSG_SESSION_PRIORITY_LOWEST, MSG_SESSION_PRIORITY_LOW, MSG_SESSION_- 
PRIORITY_NORMAL, MSG_SESSION_PRIORITY_HIGH, 


MSG_SESSION_PRIORITY_HIGHEST } 


Represents the values of session priority. 


enum _MSG MESSAGE PRIORITY_E { MSG MESSAGE PRIORITY_LOW, MSG _- 
MESSAGE_PRIORITY_NORMAL, MSG_MESSAGE_PRIORITY_HIGH } 


Represents the values of message priority. 


enum _MSG_STATUS_E { 


MSG_STATUS_UNKNOWN = 0, MSG_STATUS_READ, MSG_STATUS_UNREAD, MSG_- 
STATUS_REPLIED, 


MSG_STATUS_FORWARDED, MSG_STATUS_DRAFT, MSG_STATUS_EDITING, MSG_- 
STATUS_PROTECTED, 


MSG_STATUS_SENDING, MSG_STATUS_SENT, MSG_STATUS_FAIL_TO_SEND, MSG_- 
STATUS_SAVED_NOTSENT, 


MSG_STATUS_SENT_NOTSAVED, MSG_STATUS_SENT_SAVED, MSG_STATUS_FAIL - 
TO_SENDSAVE, MSG_STATUS_REQ_CANCELLED, 


MSG_STATUS_USER_DEF_BEGIN = 0x08000000 } 


Represents the values of status. 


enum _MSG_REQUEST_TYPE E { 


MSG_REQUEST_TYPE_INVALID = 0, MSG_REQUEST_TYPE_RESERVED_BEGIN, MSG_- 
REQUEST_TYPE_SEND, MSG_REQUEST_TYPE_SENDSAVE, 


MSG_REQUEST_TYPE_RESERVED_END = MSG_REQUEST_TYPE_RESERVED_BEGIN + 
0x00001000, MSG_REQUEST_TYPE_USER_DEF_BEGIN = 0x08000000 } 
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Represents the values of request types. 


enum _MSG_STORAGE ID _VALUE_E { MSG STORAGE UNKNOWN = 0, MSG _- 
STORAGE _ DEFAULT } 

enum _MSG_MEDIA_TYPE_E [ MSG_MEDIA_FLASH, MSG_MEDIA_REMOVABLE, MSG_- 
MEDIA_SIM } 


Represents the values of media types. 


enum _MSG_FOLDER_TYPE_E { 


MSG_FOLDER_TYPE_ROOT, MSG _FOLDER_TYPE_ INBOX, | MSG_FOLDER_TYPE_- 
OUTBOX, MSG_FOLDER_TYPE_DRAFTS, 


MSG_FOLDER_TYPE_SENT, MSG_FOLDER_TYPE DELETED, MSG _FOLDER_TYPE_- 
USERDEFINE } 


Represents the values of folder types. 


enum _MSG_CONTACT_TYPE_E { MSG_CONTACT_TYPE_UNKNOWN = 0, MSG _- 
CONTACT_TYPE_EMAIL, MSG_CONTACT_TYPE_PLMN } 


Represents the values of Contact types. 


enum _MSG_ENCODE_TYPE E { 


MSG_ENCODE_UTF8, MSG_ENCODE_UTF16, MSG_ENCODE_ASCII, MSG_ENCODE_- 
GSM7BIT, 


MSG_ENCODE_UCS2, MSG_ENCODE_SHIFT_JIS } 


Represents the values of String encoding types. 


enum _MSG_SIZE UNIT_E { 


MSG_SIZE_UNIT_BYTE, MSG_SIZE_UNIT_KBYTE, MSG_SIZE UNIT_MBYTE, MSG_- 
SIZE_UNIT_GBYTE, 


MSG_SIZE_UNIT_NUMBER } 


6.16.2 Define Documentation 


6.16.2.1 #define bool unsigned char 


Defines bool type. 


6.16.2.2 #define false 0 


Defines false value. 


6.16.2.3 define MSG_DEFAULT_ACCOUNT_ID 0 


Defines default account id. 


6.16.2.4 define MSG_DEFAULT_FOLDER_ID 0 


Defines default folder id. 
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6.16.2.5 #define MSG_ERROR_BEGIN (-255) 


Defines begin value for error. 


6.16.2.6 #define MSG_INVALID_ACCOUNT_ID Oxffff 


Defines invalid id for account. 


6.16.2.7 #define MSG_INVALID_FOLDER_ID Oxffff 


Defines invalid id for folder. 


6.16.2.8 #define MSG_INVALID_ MESSAGE _ID Oxffffffff 


Defines invalid id for message. 


6.16.2.9 #define true 1 


Defines true value. 


6.16.3 Typedef Documentation 


6.16.3.1 typedef struct MSG ACCOUNT_ID_LIST_S MSG_ACCOUNT_ID_LIST_S 


6.16.3.2 typedef unsigned int MSG_ACCOUNT_ID_T 


Represents an account id. 


6.16.3.3 typedef int MSG_CONTACT_TYPE_T 


Represents a contact type. 


The values eor this type SHOULD be in _MSG_CONTACT_TYPE_E 


6.16.3.4 typedef int MSG_ENCODE_TYPE_T 


Represents an encoding type. 


The values for this type SHOULD be in _MSG_ENCODE_TYPE_E 


6.16.3.5 typedef int MSG_ERROR_T 


Represents an error code. 


The values for this type SHOULD be in _MSG_ERROR_E 
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6.16.3.6 typedef struct MSG FOLDER_ID_LIST_S MSG FOLDER _ID_LIST_S 


6.16.3.7 typedef unsigned int MSG_FOLDER_ID_T 


Represents a folder id. 


6.16.3.8 typedef unsigned int MSG_FOLDER_TYPE_T 
Represents a folder type. 

The values for this type SHOULD be in _MSG_FOLDER_TYPE_E 
6.16.3.9 typedef int MSG_MAIN_TYPE_T 


Represents a message main type. 


The values for this type SHOULD be in _MSG_MAIN_TYPE_E 


6.16.3.10 typedef unsigned int MSG_MEDIA_TYPE_T 


Represents a media type. 


The values for this type SHOULD be in MSG _MEDIA_TYPE_E 


6.16.3.11 typedef struct MSG_MESSAGE_ID_LIST_S MSG_MESSAGE_ID_LIST_S 


6.16.3.12 typedef unsigned long MSG_MESSAGE_ID_T 


Represents a messsage id. 


6.16.3.13 typedef int MSG_MESSAGE_PRIORITY_T 


Represents a message priority. 


The values for this type SHOULD be in _MSG_MESSAGE_PRIORITY_E 


6.16.3.14 typedef struct _MSG_MESSAGE_TYPE_LIST_S MSG_MESSAGE_TYPE_LIST_S 


6.16.3.15 typedef struct _MSG_MESSAGE_TYPE_S MSG_MESSAGE_TYPE_S 


6.16.3.16 typedef unsigned int MSG_PLUGIN_ERROR_T 


Error code specific for plugins. 


6.16.3.17 typedef unsigned int MSG_REQUEST_ID_T 


Represents a request id, which is unique for each request. 


For details of request, please refer to Request . 
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6.16.3.18 typedef int MSG_REQUEST_TYPE_T 

Represents a request type. 

The values for this type SHOULD be in _MSG_REQUEST_TYPE_E 
6.16.3.19 typedef int MSG_SESSION_PRIORITY_T 

Represents a session priority. 

The values for this type SHOULD be in _MSG_SESSION_PRIORITY_E 
6.16.3.20 typedef int MSG_SIZE_UNIT_T 


Represents the unit of the size. 


The values for this type SHOULD be in _MSG_SIZE_UNIT_E 


6.16.3.21 typedef int MSG_STATUS_T 


Represents a status. 


The values for this type SHOULD be in _MSG_STATUS_E 


6.16.3.22 typedef struct _MSG_STORAGE_ID_LIST_S MSG STORAGE ID _LIST_S 


6.16.3.23 typedef unsigned int MSG_STORAGE_ID_T 
Represents a Storage id. 

For details please refer to Storage . 

6.16.3.24 typedef struct MSG _STRING_S MSG STRING S 
6.16.3.25 typedef int MSG_SUB_TYPE_T 


Represents a message sub type. 


Each main type message can be divided into some sub types. For instance of SMS, the sub types can be 
CLASSO SMS, CLASS2 SMS and so on. 
6.16.4 Enumeration Type Documentation 


6.16.4.1 enum _MSG_CONTACT_TYPE_E 


Represents the values of Contact types. 

When MSG_CONTACT_TYPE_EMAIL is used, the contact value is an email address; When MSG_- 
CONTACT_TYPE_PLMN is used, the contact value is a mobile number. 

Enumerator: 


MSG_CONTACT_TYPE_UNKNOWN The contact type is unknown 
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MSG_CONTACT_TYPE_EMAIL The contact type is for email address 
abc@example.comemail 


MSG_CONTACT_TYPE_PLMN The contact type is for phone number like +1012345678 


6.16.4.2 enum_MSG_ENCODE_TYPE_E 
Represents the values of String encoding types. 


Enumerator: 
MSG_ENCODE_UTF8 The string encoding type is UTF8 
MSG_ENCODE_UTFI16 The string encoding type is UTF16 
MSG_ENCODE_ASCIT The string encoding type is ASCII 
MSG_ENCODE_GSM7BIT The string encoding type is GSM7BIT 
MSG_ENCODE_UCS2 The string encoding type is UCS2 
MSG_ENCODE_SHIFT_]JIS The string encoding type is Shift JIS 


6.16.4.3 enum_MSG_ERROR_E 


Represents the values of error codes. 


Success code is zero, all error codes SHOULD be negative and smaller than MSG_ERROR_BEGIN 


Enumerator: 


MSG_SUCCESS Successful 

MSG_ERR_FS_ERROR File system error 

MSG_ERR_FS_FULL File system is full 
MSG_ERR_INVALID_STORAGE Storage id is invalid 
MSG_ERR_INVALID_MSG_TYPE Message type is invalid 
MSG_ERR_INVALID_SORT_TYPE Sort type is invalid 
MSG_ERR_INVALID_FOLDER_ID Folder Id is invalid 
MSG_ERR_INVALID_STORAGE_REG Storage registry is invalid 
MSG_ERR_INVALID CONNECTION Connection is invalid 
MSG_ERR_NULL_POINTER Pointer is NULL 
MSG_ERR_INVALID_MESSAGE_ID Message id is invalid 
MSG_ERR_INVALID_ACCOUNT_ID Account id is invalid 
MSG_ERR_INVALID_QUERY_ID Query id is invalid 
MSG_ERR_SESSION_NOT_CONNECTED Session is not connected 
MSG_ERR_INVALID_SESSION_HANDLE Session handle is invalid 
MSG_ERR_PERMISSION_DENIED Permisssion is denied 
MSG_ERR_STORAGE_NOT_INIT Storage is not initialized 
MSG_ERR_STORAGE_REG_NOT_INIT Storage registry is not initialized 
MSG_ERR_INVALID_SESSION_PRIORITY Session priority is invalid 
MSG_ERR_INVALID_FILTER_ID Filter Id is invalid 


like 
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MSG_ERR_INVALID_REQUEST Request is invalid: Request type is unsupported; The message 
type in request is invalid. 


MSG_ERR_INVALID_FOLDER_TYPE Folder type is invalid 
MSG_ERR_INVALID_FOLDER Folder information is invalid 
MSG_ERR_NOT_EMPTY_FOLDER Folder is not empty 
MSG_ERR_INVALID_ACCOUNT Account information is invalid 
MSG_ERR_CONNECTION_NOT_CONNECT Connection is not connected 
MSG_ERR_INVALID_MESSAGE Connection is not connected 
MSG_ERR_STORAGE_FULL Storage is full 
MSG_ERR_ROOTFOLDER_INUSE Root folder is associated with account(s) 
MSG_ERR_STORAGE_ERROR Storage is error 
MSG_ERR_MEMORY_ERROR Memory is error 
MSG_ERR_COMMUNICATION_ERROR Communication between client and server is error 


MSG_ERR_MAX_NUMBER_REACHED Max number reached when adding message,account or 
folder 


MSG_ERR_INVALID_REQUEST_ID Request Id is invalid 

MSG_ERR_UNKNOWN Unknown errors 
MSG_ERR_FRAMEWORK_RESERVE_BEGIN Framework reserved error code begin value 
MSG_ERR_FRAMEWORK_RESERVE_END Framework reserved error code end value 
MSG_ERR_PLUGIN Generic error code for plugin 


MSG_ERR_PLUGIN_DEF_BEGIN_VALUE Plugin defined error code begin value. It's equal to 
MSG_ERR_PLUGIN 


6.16.4.4 enum_MSG_FOLDER_TYPE_E 


Represents the values of folder types. 


Enumerator: 
MSG_FOLDER_TYPE_ROOT Root folder 
MSG_FOLDER_TYPE_ INBOX InBox folder 
MSG_FOLDER_TYPE_OUTBOX OutBox folder 
MSG_FOLDER_TYPE_DRAFTS Draft folder 
MSG_FOLDER_TYPE_SENT Sent folder 
MSG_FOLDER_TYPE_ DELETED Trash folder 
MSG_FOLDER_ TYPE _USERDEFINE Folder is created by user 


6.16.4.5  enum_MSG_MAIN_TYPE_E 


Represents the values of message main types. 


Four message main types are predefined: SMS, MMS, Email and iMode. More main message types can be 
defined here. 
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Enumerator: 


MSG_MESSAGE_TYPE_UNKNOWN Unknown message type 
MSG_MESSAGE_TYPE_MMS MMS message 
MSG_MESSAGE_TYPE_EMAIL Email message 
MSG_MESSAGE_TYPE_SMS SMS message 
MSG_MESSAGE_TYPE_IMODE i-mode message 


6.16.4.6 enum _MSG MEDIA _TYPE_E 
Represents the values of media types. 


Enumerator: 


MSG_MEDIA_FLASH Media type is flash 
MSG_MEDIA_REMOVABLE Media type is removable 
MSG_MEDIA_SIM Media type is SIM card 


6.16.4.7 enum _MSG MESSAGE PRIORITY_E 
Represents the values of message priority. 


Enumerator: 


MSG_MESSAGE_PRIORITY_LOW Low priority 
MSG_MESSAGE_PRIORITY_NORMAL Normal priority 
MSG_MESSAGE_PRIORITY_HIGH High priority 


6.16.4.8 enum _MSG_ REQUEST_TYPE_E 


Represents the values of request types. 


This enum is used as the value of type MSG_REQUEST_TYPE_T. Each message plugin can define the 
supported request types in this enum. Application can use the request type to invoke plugin corresponding 
operation via framework. Note that the enum between MSG_REQUEST_TYPE_RESERVED_BEGIN and 
MSG_REQUEST_TYPE_RESERVED_END are reserved for framework. For details of request, please 
refer to Request . 


Enumerator: 


MSG_REQUEST_TYPE_INVALID It’s used as the initial value to request type. 
MSG_REQUEST_TYPE_RESERVED_BEGIN Framework reserved begin value 
MSG_REQUEST_TYPE_SEND Request to send message. 

This request is used to send a message. After this request is submitted, following status may be 

triggered: 

MSG_STATUS_SENDING: Message is in sending. 

MSG_STATUS_SENT: Messag is sent successfully. 

MSG_STATUS_FAIL_TO_SEND: Message is fail to send. 

If the request is cancelled successfully, the message is not sent and following status is triggered: 

MSG_STATUS_REQ_ CANCELLED: Request is cancelled. 
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MSG_REQUEST_TYPE_SENDSAVE Request to send and save message. 
This request is used to send and save a message. After this request is submitted, following status 
may be triggered: 
MSG_STATUS_SENDING: Message is in sending. 
MSG_STATUS_SAVED_NOTSENT: Messag is saved but not sent. 
MSG_STATUS_SENT_NOTSAVED: Message is sent but not saved. 
MSG_STATUS_SENT_SAVED: Message is both saved and sent. 
MSG_STATUS_FAIL_TO_SENDSAVE: Message is neither saved nor sent. 
If the request is cancelled successfully, the message is not sent and not saved. Following status 
is triggered: 
MSG_STATUS_REQ_ CANCELLED: Request is cancelled. 
MSG_REQUEST_TYPE_RESERVED_END Framework reserved end value 


MSG_REQUEST_TYPE_USER_DEF_BEGIN User defined request type begin value 


6.16.4.9 enum _MSG_SESSION_PRIORITY_E 
Represents the values of session priority. 


Enumerator: 
MSG_SESSION_PRIORITY_LOWEST Lowest priority 
MSG_SESSION_PRIORITY_LOW Low priority 
MSG_SESSION_PRIORITY_NORMAL Normal priority 
MSG_SESSION_PRIORITY_HIGH High priority 
MSG_SESSION_PRIORITY_HIGHEST Highest priority 


6.16.4.10 enum _MSG_SIZE_UNIT_E 


Enumerator: 
MSG_SIZE_UNIT_BYTE Unit is byte 
MSG_SIZE_UNIT_KBYTE Unit is kilo-byte 
MSG_SIZE_UNIT_MBYTE Unit is mega-byte 
MSG_SIZE_UNIT_GBYTE Unit is giga-byte 
MSG_SIZE_UNIT_NUMBER Unit is number 


6.16.4.11 enum _MSG_STATUS_E 


Represents the values of status. 


This enum is used as the value of type MSG_STATUS_T. The specific status for each message can be 
defined in this enum. For instance of Email, sending status can be defined to track the email sending 
progress. 


Enumerator: 


MSG_STATUS_ UNKNOWN Unknown status 
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MSG_STATUS_READ Message is read 

MSG_STATUS_UNREAD Message is unread 
MSG_STATUS_REPLIED Message is replied 
MSG_STATUS_FORWARDED Message is forwarded 
MSG_STATUS_DRAFT Message is draft 

MSG_STATUS_EDITING Message is in editing 
MSG_STATUS_PROTECTED Message is protected 
MSG_STATUS_SENDING Message is sending 
MSG_STATUS_SENT Message is sent 
MSG_STATUS_FAIL_TO_SEND Message is fail to send 
MSG_STATUS_SAVED_NOTSENT Message is saved, but not sent 
MSG_STATUS_SENT_NOTSAVED Message is sent, but not saved 
MSG_STATUS_SENT_SAVED Message is sent and saved 
MSG_STATUS_FAIL_TO_SENDSAVE Message is not saved and not sent 
MSG_STATUS_REQ_ CANCELLED Request is cancelled 
MSG_STATUS_USER_DEF_BEGIN User defined status begin value 


6.16.4.12 enum _MSG_STORAGE ID_VALUE_E 


Enumerator: 


MSG_STORAGE_UNKNOWN 
MSG_STORAGE_DEFAULT The default storage 
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7.1 Overview of the LiMo Messaging API 


The following sections describe the Common structures and MAPI Functions the LiMo Messaging API 
provides to the application. In addition, the concepts of a Session and Request are discussed. 


7.1.1 Common structures 


In MAPI, there are few main concepts of data: 


e Message 
e Folder 


e Account 


7.1.1.1 Message 


In LiMo messaging, a message represents data for a SMS, MMS, e-mail or i-mode message. A message is 
not specific to any one service, but supports the extension of this structure. For service-specific messages, 
please refer to Extendability. 


Each message has a unique messageld in the entire messaging framework. The message information 
can be retrieved from the storage by its messagelad. 


For each message, there is one account attached to it. The concept is embodied on there is account Id 
field in _MSG_MESSAGE, $. If storageld field is not set, then the default Storageld in attached 
account would be used. For more information on account, please refer to Account 


This concept is defined in Msg_Mapi_Message.h 


7.1.1.2 Folder 


A folder represents a container of messages or other folders. It should have only one parent folder, and 
zero or more children. 


Each folder has a unique folderId in the entire messaging framework. The folder information can be 
retrieved from the storage by its folderId. 
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A folder can specify where it is stored. The storage where a folder is stored can be different from the 
storage where its containing messages are stored. 


One of special folders is called "root folder", which is top-level folder and contains five predefined folders, 
which are: 


+ INBOX, 

OUTBOX, 
e DRAFTS, 
+ SENT, and 
DELETED 


The predefined folders cannot be created or deleted individually, instead they can be created and deleted 
during the corrsponding operations on its root folder. 


This concept is defined in Msg Mapi_Folder.h 


7.1.1.3 Account 


An account represents the personal setting information for a message type. For example, an e-mail account 
can include such information as e-mail address, and SMS can include message center number. 


Each account has a unique account Id in the entire messaging framework. The account information can 
be retrieved from the storage by its account Id. The account id is the reference being used by other types 
of structure, such as message and folder. 


A message type can be associated with more than one accounts, and has one default account. However, one 
message has only one account. If application has not selected any account, then the default account takes 
effect. An account has an attribute called root Folder, which defines the root folder having association 
with that account. As name suggested, rootFolder field needs to be set with root folder only, other 
folder cannot be set. A folder could be shared among different accounts. 


This concept is defined in Msg Mapi_Account.h 


7.1.2 Session, Request and Filter Rules 
7.1.2.1 Session 


Session is the connection between application and MAPI for message reception and transmission. 
When an application wants to send or receive a message, it must create and connect a session first. A 
session can be assigned with following information: 

e Register MsgOnMessageIncomingCallback function. 

e Register MsgOnStatusChangedCallback function. 

e Set priority. For details please refer to MsgSetPriority 

e Set filter rule. 
One application can create and connect more than one sessions, different sessions can be assigned with 
different priorities and filter rules. 


To know how to use asynchronous callback for communication between application and framework, please 
refer to Callback Functions 
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7.1.2.2 Request 


A request contains the information that is used to command framework for services, such as sending a 
message. A request is sent to Messaging Framework via a session, and Messaging Framework chooses 
proper plugin to handle the request. 


A common usage for the request is to send a message. And the request type is predefined as MSG_- 
REQUEST_TYPE_SEND. 


This concept is defined in Msg_Mapi_Message_Request.h 


7.1.2.3 Callback Functions 


Callback is used by application to detect incoming message and underlayer status change. Two callback 
functions prototype are provided: 


e one is MsgOnMessageIncomingCallback, which is to listen incoming message, 


e the other is MsgOnStatusChangedCallback, which is to listen underlayer status change. 


Both callback functions are implemented by applications and should be bound to a session. 


7.1.2.4 Filter and Filter List 
When an application is only interested in some kinds of messages, filter list is used to filter these specific 
messages and return them to the application. 


Noted that filter is for filtering incoming messages, not a storage concept. For storage, the filter concept is 
called Query. 


Filter is the basic unit to set the rules, it tells the filter service how to filter the message. Filter list is 
composed of various filters. They are defined in Msg_Mapi_FilterRule.h . 


Application can set a filter list for a session to get the interesting message. Please refer to _MSG_FILTER_S 
and _MSG_FILTER_LIST_S for details. 


MAPI does NOT define any filters. Application developers should refer to the specific implementation of 
filter service to get the supported filters. 


7.1.3 Storage 
7.1.3.1 Connection 


A connection is a logical concept between client application and LiMo Messaing framework. It does NOT 
represent the physical storage connection underneath the MAPI. A connection is required by the storage 
functions, such as adding message, as their first parameter. 


There are found status in connection’s life-cycle: 


e created(but-not-yet-connected), 
* connected, 
e disconnected and 


e destroyed. 
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The following functions are responsible to change life-cycle status: 


e MsgCreateStoConnection 
e MsgOpenStoConnection 
e MsgCloseStoConnection 


e MsgDestroyStoConnection 


For more information, please refer to Msg_Mapi_Storage_Manager.h 


7.1.3.2 Storage 


Storage is a collection of messages and related information that are stored on one storage media. Storage 
media is the physical data storage device, such as SD card and Flash. One storage media can have more 
than one storages. 


For example, on flash storage media, there are two storages which are located at two different folders: 
/flash/Folder1/ and /flash/Folder2/ respectively. Since storage media can be removable, the storages on the 
media can be detached and attached dynamically. For instance, user plugs out SD card from UE 1 and 
plugs in this card into UE 2, all the messages stored in this card will be hidden from UE 1 and be visible to 
UE 2. 


For details information, please refer to_MSG_STORAGE_ REGISTRY_S 


Application can query supported storages by MAPI method MsgListStorageRegistry and MsgGetStor- 
ageRegistry. 


For sample code, please refer to Storage General: Initializing Storage 


7.1.3.3 Query 


LiMo Messaging supports query on message retrieval from storage. 


Query rule, represented by MSG_QUERY_S, is a rule to specify a single search criteria for messages. 
Query rule list, represented by MSG_QUERY_LIST_S, is composed of a number of query rules. If one 
message satisfies one of query rule in the list, it satisfies the query rule list. 


For more information on how to use Query, please refer to MsgQueryMessage . 


7.1.3.4 Sort 


LiMo Messaging supports sort on message retrieval from storage. 


Sort rule, represented by _MSG_SORT_RULE,_S, defines which field in message structure is sorted on, 
and how this field is sorted. 


Sort type, represented by _MSG_SORT_TYPE_T, defines which field can be sorted on. 


For more information on how to use Sort, please refer to MsgQueryMessage . 


7.1.4 Extendability 


There are several structures in LiMo Messageing designed to be extended. They are: 
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e _MSG_ACCOUNT_S 
e _MSG_FOLDER_S 
e _MSG_MESSAGE_S 


_MSG_MESSAGE_REQUEST_S 


In these structures, there are two fields for data extension, which are : 


e pExtData 


e extDataSize 


pExtData, of type void x, can hold a pointer to any structure. Noted that the pointed structure cannot 
contain any pointer as its field, since the extended data will be treated as a memory block to pass around 
between applications and plugins, any inside pointer would not be handled properly. 


extDataSize, of type size_t, indicates the length of the pExtData block. 


7.1.5 MAPI Functions 


This section describes the functions that MAPI provides. 


7.1.5.1 Message Sending and Receiving 


The Message sending and receiving module provides the unique interfaces to send and receive messages. 
The Session structure is the primary structure to hold the connection information. Applications use Session 
to send and receive messages. 


The major functionality that the message sending and reception module provides are: 


Creating and destroying session handle: MsgCreateSession and MsgDestroySession, respectively. 


Connecting and disconnecting session handle: MsgConnectSession and MsgDisconnectSession . 


Defining the callback functions prototypes: on message received and on status changed. See Ms- 
gOnMessagelncomingCallback and MsgOnStatusChangedCallback. 


Registering the callback functions on session handle: MsgRegMessageCallback and MsgRegStatus- 
Callback. 


Setting priority and filter list on session handle. See MsgSetPriority and MsgSetFilterList. 


Submitting and cancelling a request; MsgSubmitReq and MsgCancelReq. 


The following is the file for this module: 


e Msg_Mapi_Session.h 


For more information, please see the sample code: 


e Sending a Message 


e Receiving Messages 
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7.1.6 Storage Functionality 


7.1.6.1 Storage Management 


The Storage management module provides the management functionality for storage such as storage reg- 
istry Operations, storage data initialization etc. The major functions that the Storage Management module 
provides are: 


Listing and getting storage registration information. See MsgListSortType and MsgGetStorageReg- 
istry. 


Creating, opening, closing, and destroying connection; MsgCreateStoConnection, MsgOpenStoCon- 
nection, MsgCloseStoConnection, and MsgDestroyStoConnection, respectively. 


Getting Framework Storage and Message Storage status. See MsgGetFwStorageStatus and 
MsgGetMsgStorageStatus. 


Releasing memory of storage id list and storage registry information. See MsgReleaseStorageldList 
and MsgReleaseStorageRegistry. The following is the file for this module: 


Msg_Mapi_Storage_Manager.h 


For more information, please see the sample code: 


Initializing Storage 


7.1.6.2 Message Storage 


The major functions that the message storage module provides are: 


Adding and updating messages; MsgAddMessage and MsgUpdateMessage. 


Counting messages and counting unread messages. See MsgCountMessage and MsgCountUn- 
readMessage. 


Moving messages. See MsgMoveMessageToFolder and MsgMoveMessageToStorage. 
Querying messages: MsgQueryMessage. 
Getting message ids by storage. See MsgGetMessageldsByStorage. 


Getting message detail information, getting message common information and getting message par- 
ent folder. Refer to MsgGetMessage, MsgGetMessageCommInfo and MsgGetMessageParentld. 


Releasing memory of message detail information (MsgReleaseMessage) and message common in- 
formation (MsgReleaseMessageCommInfo). 


The functionality is defined in: 


Msg_Mapi_Storage_Message.h. 


For more information, please see the sample code: 


Creating and Storing a Message 


Retrieving Message List and Entity 
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7.1.6.3 Folder Storage 


The major functionality that folder storage module provides: 


Adding and updating folders: MsgAddFolder and MsgUpdateMessage. 
Counting and querying folders: MsgCountSubFolder and MsgQueryFolder. 
Moving folders. Please see MsgMoveFolderToFolder and MsgMoveFolderToStorage 


Getting folder ids by storage and getting all root folder ids. See MsgGetFolderldsByStorage and 
MsgGetAllRootFolderlds. 


Getting the specified folder (MsgGetFolder) and getting parent folder id (MsgGetFolderParentld). 


Releasing memory of folder: MsgReleaseFolder. 


The functionality is defined in: 


Msg_Mapi_Storage_Folder.h 


For more information, please see the sample code: 


Creating and Storing a Folder 


Querying Folders 


7.1.6.4 Account Storage 


The major functionality that the Account storage module provides: 


Adding and updating. See MsgAddAccount and MsgUpdateAccount. 

Counting (MsgCountAccount) and querying (MsgQuery Account) accounts in storage. 

Moving accounts. See MsgMoveAccountToStorage. 

Getting account ids by storage. See MsgGetAccountldsByStorage. 

Getting the specified account in storage: MsgGetAccount. 

Getting and setting default account id: MsgGetDefaultAccountID and MsgSetDefaultAccountID. 
Getting account common information: MsgGetCommAccount. 


Releasing the memory of account information (MsgRelease Account) and account common informa- 
tion (MsgReleaseCommAccount). 


The functionality is defined in: 


Msg_Mapi_Storage_Account.h 


For more information, please see the sample code: 


Creating and Storing an Account 
Updating an Account 


Getting a Default Account 
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7.2 Sample Code for Using the LiMo Messaging API 


The following samples of application code demonstrate many of the tasks an application programmer will 
need to perform. 


Extending a Message Structure 
Sending a Message 

Receiving Messages 

Initializing Storage 

Creating and Storing a Message 
Retrieving Message List and Entity 
Creating and Storing an Account 
Updating an Account 

Getting a Default Account 
Creating and Storing a Folder 


Querying Folders 
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7.3 Extending a Message Structure 


Since LiMo MAPI provides only a generic message, the sample code below demonstrates how to make 
SMS a specific message service. This requires an extended Account structure as defined below. All the 
extended structures should be shared between applications and plug-ins. Plug-in developers should imple- 
ment all the plug-in interface functions based on these extended structures, and application developers can 
use these extended structures in their own application. 


MSG_ERR_USER_DEFINED represents an application-defined error code. Applications should define 
their own error codes in their implementations. 


typedef struct _MSG_MESSAGE_SMS_EXTDATA_S 
{ 


char * pBody; //Body 

char * pScAddr; //Service Center 

int expirePeriod; //expirePeriod 
)_MSG_MESSAGE_SMS_EXTDATA_S; 


// This structure is the extended structure for _MSG_ACCOUNT_S, 
// which can be used as Email account structure. 

typedef struct _MSG_ACCOUNT_EMAIL_EXTDATA_S 

{ 


_MSG_STRING_S emailServerUrl; 

int portNumber; 

_MSG_STRING_S displayAddress; 
} MSG_ACCOUNT_EMATL EXTDATA_S; 


// This structure is the extended structure for _MSG_ACCOUNT_S, 
// which can be used as SMS account structure. 

typedef struct _MSG_ACCOUNT_SMS_EXTDATA_S 

{ 


_MSG_STRING_S smsServerCenter; 
int portNumber; 
bool needDeliveryReport; 
bool autoReply; 
} _MSG_ACCOUNT_SMS_EXTDATA_S; 


//The sub type enum of SMS 
enum _MSG_SMS_SUB_TYPE_E 
{ 


MSG_TYPE_SMS_TEXT 
y; 


//define the storage id enum 
enum _MSG_STORAGE_ID_E 
{ 


MSG_STORAGE_ID_FLASH, 
MSG_STORAGE_ID_SD 
y; 
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7.4 Message Session: Sending a Message 


In this section, you will learn how to send a message through LiMo MAPI. This task requires two pieces of 
structure to be prepared. One is the message structure, composed in the application The other is a Session 
structure. A connected Session is required for both sending a message, and receiving a message as will be 
demonstrated. 


This task is considered asynchronous, that means after the application sends the sending request, the event 
of request’s status will be returned afterwards through a registered callback function. 


To send a SMS, there is one precondition: there should be a SMS plug-in already plugged into the frame- 
work. The SMS plug-in should provide SMS extension structure and subtypes for SMS. To get this result, 
the application MUST implement the Callback function MsgOnStatusChangedCallback(), and register it 
to the session. 


Suppose the structure and subtype are defined as in the previous example. The callback function is defined 


as shown below. 


void MyOnStatusChange (_MSG_MESSAGE_STATUS_S * ppMsgStatus, MSG_SESSION_HANDLE_T hSession) 
{ 


//Get the request id and status from ppMsgStatus here. 


int regld; 
MSG_ERROR_T SendMessageSample () 
{ 


MSG_SESSION_HANDLE_T Session; 

MSG_MESSAGE_REQUEST_S req; 

MSG_ERROR_T err; 

_MSG_MESSAGE_S msgInfo; //Message to be sent 

_MSG_CONTACT_S to[2]; //contact array which are used by tolist 
MSG_CONTACT_LIST_S tolist; // to whom the message to be sent 
MSG_MESSAGE_SMS_EXTDATA_S SMSInfo; // SMS extension info 
MSG_STRING_S strSubject; 


err = MsgCreateSession(&Session); // Create session 
if(err != MSG_SUCCESS) //if creation failed, return error. 
return err; 


err = MsgConnectSession(Session); //Establish Session Connection. 
if(err != MSG_SUCCESS) //if connection failed, destroy SessionHandle, return error. 
{ 

MsgDestroySession (Session); 

return err; 


// Register callback function 
err = MsgRegStatusCallback (Session, MyOnStatusChange) ; 
if(err != MSG_SUCCESS) 
{ 
MsgDisconnectSession (Session) ; 
MsgDestroySession (Session); 
return err; 


//Set To 

to[0] .contactType = MSG_CONTACT_TYPE_PLMN; 

to[0].contactVal = "000"; //1st phone number to be sent. It is just a sample number. 
to[1] .contactType = MSG_CONTACT_TYPE_PLMN; 

to[1].contactVal = "000"; //2nd phone number to be sent. It is just a sample number. 


tolist.pContacts = to; //fill tolist 
tolist.iCount = 2; 
msgInfo.to = tolist; //set tolist to msgInfo 


//Set Subject 
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strSubject.encodeType = MSG_ENCODE_ASCITI; 


strSubject.pString = "subject"; 
strSubject.length = strlen(strSubject.pString) ; 
msgInfo.subject = strSubject; 


//set msgType 
msgInfo.msgType.mainType = MSG_MESSAGE_TYPE_SMS; 
msgInfo.msgType.subType = MSG_TYPE_SMS_TEXT; 


//set user defined ext data, MAPI user can read SMS plug-in document 
// to understand the meaning of each 

SMSInfo.pScAddr = "222"; //it is just a sample number. 

SMSInfo.pBody = "This is a test SMS"; 

SMSInfo.expirePeriod = 0; 

msgInfo.pExtData = £SMSInfo; //Sent extension data to msgInfo. 


// Get the accountId used to send message and set it to msgInfo.accountId. 
// For details of account information, 


//fi11 req 

req.reqType = MSG_REQUEST_TYPE_SEND; // Set request type 
req.pMsg = &msgInfo; // Set msg 

err = MsgSubmitReq (Session, &req, &reqid); // Submit request. 


// finalize session. 

// This is just a sample to show how to finalize session. 
// Usually, application can keep a connected session 
MsgDisconnectSession (Session); 

MsgDestroySession (Session); 


return err; 
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7.5 Message Session: Receiving Messages 


In this section, you will learn how to receive incoming message in your application, through LiMo MAPI. 
In this example, only SMS messages will received and processed. Other r types of messages will be ignored 
by the application. 


To receive messages, an application MUST implement the callback function MsgOnMessagelncoming- 
Callback() and register it to session. Beyond that, an application MAY set a filter list. If a filter list is set, 
only incoming messages that satisfy the filter list will be passed to the registered callback function. In the 
code below, MyOnMsgIncome() is the callback function that implements MsgOnMessageIncomingCall- 
back(). 


void MyOnMsgIncome (_MSG_MESSAGE_S * ppMsgInfo, 
MSG_MESSAGE_STATUS_S * ppMsgStatus, 
MSG_SESSION_HANDLE_T hSession) 


switch (ppMsgInfo->msgType.mainType) 
{ 
case MSG_MESSAGE_TYPE_SMS: 
// Handle SMS message here 
break; 
case MSG_MESSAGE_TYPE_MMS: 
// Handle MMS message here 
break; 
default: 
// Handle other message here 
break; 


MSG_ERROR_T ReceiveMessageSample () 
{ 
MSG_SESSION_HANDLE_T Session; 
MSG_ERROR_T err; 
_MSG_FILTER_S filters[2]; // filter items used by filter list 
MSG_FILTER_LIST_S filterList; // filter list used by filter rule 


err = MsgCreateSession(&Session); // Create session 
if(err != MSG_SUCCESS) //if creation failed, return error. 
return err; 


err = MsgConnectSession (Session); //Establish Session Connection. 
if(err != MSG_SUCCESS) // if connection failed, destroy SessionHandle, return error. 
{ 

MsgDestroySession (Session); 

return err; 


// Register callback function 
err = MsgRegMessageCallback (Session, MyOnMsgIncome) ; 
if (err != MSG_SUCCESS) 
{ 
MsgDisconnectSession (Session) ; 
MsgDestroySession (Session) ; 
return err; 
} 
// set filters 
//filters[0] is to filter all sms messages. 
filters[0].filterld = MSG_FILTER_BY_MSG_TYPE; 
filters[0].filterValue = (unsigned char * )malloc(sizeof (unsigned char)); 
filters[0].filterValue = MSG_MESSAGE_TYPE_SMS; 
filters[0].valueLength = 1; 
//true means if message satisfies the filter, framework will save it automatically. 
filters[0].autoStore = true; 
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// true means if message satisfies the filter, it will be received 
filters[0].intercept = true; 


//filters[1] is to filter all messages with attachment. 
filters[1].filterld = MSG_FILTER_BY_HAS_ ATTACHMENT; 

filters[1].filterValue = (unsigned char * )malloc(sizeof (unsigned char)); 

filters[1].filterValue = 1; 

1 

1 

1 


filters -valueLength = 1; 
filters -autoStore = false; 
filters -intercept = false; 


// Set filterList, all the filters in filterlist are OR related, 
// former filters will be compared first. 

filterList.filters = filters; 

filterList.iCount = 2; 


// Set the filterRule to session 
MsgSetFilterList (Session, &filterList); 
if(err != MSG_SUCCESS) 
{ 
MsgDisconnectSession (Session) ; 
MsgDestroySession (Session) ; 
return err; 


// Set session priority 
MsgSetPriority (Session, MSG_SESSION_PRIORITY_NORMAL) ; 
if(err != MSG_SUCCESS) 
{ 
MsgDisconnectSession (Session); 
MsgDestroySession (Session) ; 
return err; 
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7.6 Storage General: Initializing Storage 


For message, folder and account storage, storage has to be connected prior to use. The framework is 
responsible for storage setup and initialization. The application has to connect to the framework, before 
operating storage. 


The following code illustrates how to connect and disconnect the storage connection between applications 
and framework. 
MSG_CONNECTION_HANDLE_T hConnection; 
MSG_ERROR_T InitDB() 
{ 
MSG_ERROR_T ret; 
ret = MsgCreateStoConnection(&hConnection) ; 
if(ret != false) 
ret = MsgOpenStoConnection (hConnection) ; 
return ret; 
MSG_ERROR_T Shutdown () 
MSG_ERROR_T ret; 
//TODO 
ret = MsgCloseStoConnection(hConnection); 


ret = MsgDestroyStoConnection (hConnection) ; 


return ret; 
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7.7 Message Storage: Creating and Storing a Message 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
previous example. 


The code first creates a SMS message structure, and then stores the structure into storage. 


MSG_ERROR_T StoreNewSMS (MSG_CONNECTION_HANDLE_T hConnection) 
{ 
_MSG_MESSAGE_S msgInfo; 
_MSG_CONTACT_S contactList [2]; 
MSG_CONTACT_LIST_S to; 
MSG_MESSAGE_REQUEST_S req; 
MSG_MESSAGE_SMS_EXTDATA_S SMSInfo; 
_MSG_STRING_S string[2]; 
_MSG_STRING_S subject; 
MSG_ACCOUNT_ID_T Accountld; 
MSG_ERROR_T ret; 
/ x Set To x / 
string[0].pString = "aaa"; 
string[0].length = 4; 
string[0].encodeType = MSG_ENCODE_UTF8; 
contactList[0].contactType = MSG_CONTACT_TYPE_PLMN; 
contactList[0].contactVal = ""; 
contactList[0].contactName = string[0]; 
contactList[0].extDataSize= 0; 
contactList[0].pExtData = NULL; 


string[1].pString = "bbb"; 

string[1].length = 4; 

string[1].encodeType = MSG_ENCODE_UTF8; 
contactlist[1].contactType = MSG_CONTACT_TYPE_PLMN; 
contactlist[1].contactVal = "11"; 
contactList[1].contactName = string[1]; 
contactlist[1].extDataSize= 0; 
contactList[1].pExtData = NULL; 

to.pContacts = contactList; 

to.iCount = 2; 


msgInfo.to = to; 


/ x Set Subject x / 

subject .encodeType = MSG_ENCODE_UTF8; 
subject.length = 8; 

subject.pString = "subject"; 
msgInfo.subject = subject; 


/ x set msglype * / 
msgInfo.msgType.mainType = MSG_MESSAGE_TYPE_SMS; 
msgInfo.msgType.subType = MSG_TYPE_SMS_TEXT; 


/ x set storage id x / 
msgInfo.storageId = MSG_STORAGE_ID_FLASH; 


ret = MsgGetDefaultAccountID(hConnection,msgInfo.msgType, &AccountId) ; 
if (ret == MSG_SUCCESS) 
msgInfo.accountId = Accountld; 
else 
return ret; 


/ * set parent folder x / 


/ * set priority x* / 


/ * set user defined ext data x / 
SMSInfo.pScAddr = "+11"; 
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SMSInfo.pBody = "This is a test SMS"; 


SMSInfo.expirePeriod = 0; 
msgInfo.pExtData = &SMSInfo; 
msgInfo.pCommExtData = NULL; 
/ * Store Message * / 


return MsgAddMessage (hConnection, &msgInfo) ; 
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7.8 Message Storage: Retrieving Message List and Entity 


Pre-condition: The storage has to be properly set up and initialized. To setup a storage, please refer to the 
Initializing Storage example. 


The code below queries a number of messages in a specific folder with query rules, and iterates the message 
list to handle each message. 


e hConnection is a client-server connection for storage. 


e folderld indicates which folder is the parent folder containing all expected messages. 


MSG_ERROR_T QueryMsg (MSG_CONNECTION_HANDLE_T hConnection ) 
{ 
MSG_ERROR_T ret; 
int i; // counter for result list iteration. 
MSG_MESSAGE_ID_LIST_S msgIdList; 
MSG_QUERY_LIST_S sQueryList; 
_MSG_QUERY_S sQuery [2]; 
MSG_SORT_RULE_S SortRule; 
MSG_FOLDER_ID_T Folderld; 
_MSG_MESSAGE_S **ppMsg; 
// Create a query list. 
sQuery[0].queryId = MSG_QUERY_BY_SUBJECT; 
sQuery[0].queryValue = "Hello"; 
sQuery[0].valueLength = 6; 


sQuery[1].queryId = MSG_QUERY_BY_FROM; 
sQuery -queryValue = "139 xxxxxxxx "; 


sQuery[1].valueLength = 14; 


bh 


sQueryList.queries = sQuery; 
sQueryList.iCount = 2; 

/ x set sort rule « / 

SortRule.sortType = MSG_SORT_BY_DISPLAY_TIME; 
SortRule.isAscending = true; 


/ x get and set folder id « / 
FolderId = 2; / * such as: 2 represents INBOX * / 


ret = MsgQueryMessage( hConnection, Folderld, 

0, / x iBeginIndex * / 

-1, / * iCount. -1 means all records in the folder. x / 
&SortRule, 

é&sQueryList, 

émsgIldList) ; 


if (ret != MSG_SUCCESS ) 
{ 
return ret; 
} 
// Iterate the result list 
i = msgldList.iCount; 
while (i>0) 
{ 
ret = MsgGetMessage( hConnection, ( * (msgIdList.msgIds))++, ppMsg) ; 
if (ret != MSG_SUCCESS ) 
{ 
/ * abnormity handle x / 
} 
/ * add use ppMsg code here « / 


MsgReleaseMessage( * ppMsg); 
i--; 
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MsgReleaseMessageldList (8$msgldList); 
return ret; 
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7.9 Folder Storage: Creating and Storing a Folder 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
Initializing storage example. 


The code below creates a folder under a specified parent folder. 


//create user defined folder 
MSG_ERROR_T CreateFolder (MSG_CONNECTION_HANDLE_T hConnection, MSG_FOLDER_ID_T parentFolderld) 


{ 


MSG_ERROR_T ret; 
_MSG_FOLDER_S folderInfo; 
_MSG_FOLDER_S *x*ppParentFolder; 


//get connection handle 
if( hConnection == NULL ) 
return MSG_ERR_USER_DEFINED; 


//get parent folder 
ret = MsgGetFolder(hConnection, parentFolderld, 
if( ret != MSG_SUCCESS ) 
{ 
MsgReleaseFolder( * ppParentFolder) ; 
return MSG_ERR_USER_DEFINED; 


//set the folder information which is to add, 


folderInfo.folderName.pString= "MyFolder"; 
folderInfo.folderName.length = 8; 
folderInfo.folderId = MSG_INVALID_ID; 
folderInfo.parentld = parentFolderld; 


folderInfo.commExtDataSize = 0; 
folderInfo.pCommExtData = NULL; 


//add folder 
ret = MsgAddFolder (hConnection, £folderInfo); 


MsgReleaseFolder( * ppParentFolder) ; 


return ret; 


ppParentFolder) ; 


folderInfo.folderName.encodeType = MSG_ENCODE_ASCII; 


folderInfo.storageId = ( * ppParentFolder)->storageld; 
folderInfo.sortType = MSG_SORT_BY_DISPLAY_SUBJECT; 
folderInfo.folderType = MSG_FOLDER_TYPE_DELETED; 
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7.10 Folder Storage: Querying Folders 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
Initializing storage example. 


The code below queries subfolders of a specific parent folder. There are two required parameters: 


e hConnection represents a client-server connection for storage. 


e folderld indicates which folder is the parent folder containing all expected messages. expected fold- 
ers. 


//Querying folder 
MSG_ERROR_T QueryFolders (MSG_CONNECTION_HANDLE_T hConnection, MSG_FOLDER_ID_T folderld) 
{ 

MSG_ERROR_T ret; 


//connection handle 
if( hConnection == NULL ) 
return MSG_ERR_USER_DEFINED; 


//query the direct child folders of a specific parent folder 
MSG_FOLDER_ID_LIST_S folderList; 

ret = MsgQueryFolder(hConnection, folderld, 0, 0, &folderList) ; 
if( ret != MSG_SUCCESS ) 

{ 


MsgReleaseFolderldList (8$folderList); 
return MSG_ERR_USER_DEFINED; 


// user can do something to the child folders which is just searched out. 


//free allocated memory 
MsgReleaseFolderldList (&folderList) ; 
return ret; 
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7.11 Account Storage: Creating and Storing an Account 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
Initializing storage example. The code below is to create account. There is one required parameter: 


e hConnection represents a client-server connection for storage. 


MSG_ERROR_T CreateAccount (MSG_CONNECTION_HANDLE_T hConnection) 
{ 
MSG_ERROR_T ret; 
_MSG_ACCOUNT_S account; 
MSG_FOLDER_ID_LIST_S folderList; 
MSG_STORAGE_ID_LIST_S storageIdList; 


//connection handle 
if( hConnection == NULL ) 
return MSG_ERR_INVALID_CONNECTION; 


account.accountId = MSG_INVALID_ID; 


//account name and type 
account.accountName.encodeType = MSG_ENCODE_ASCII; 
account.accountName.pString = "TestAccount"; 
account.accountName.length = 11; 
account.msgType.mainType = MSG_MESSAGE_TYPE_SMS; 
account.msgType.subType = MSG_TYPE_SMS_TEXT; 


//Setting the storage id. 

//For the testing purpose, the first storage id of the querying result is used as 

//the storage of account, and the second is for the default storage of message. 

MSG_STORAGE_ID_T stoldl, stold2; 

MsgListStorageRegistry(hConnection, &storagelIdList) ; 

if (storageIdList.iCount > 1) 

{ 
stoIdl = storageldList.pStoragelds[0]; 
stoId2 = storageIdList.pStoragelIds[1]; 

} 

else if (storageIdList.iCount == 1) 

{ 
stoldl = storageldList.pStoragelds[0]; 
stold2 = storageldList.pStoragelds[0]; 


} 


else 


{ 


return MSG_ERR_USER_DEFINED; 
} 
account.storageld = stoldl; 
account .defaultMsgStorageld = stold2; 
MsgReleaseStorageldList (&storagelIdList) ; 


//setting the root folder of this account, for the test purpose we simply use 
//the first root folder from the queried result. 
ret = MsgGetAllRootFolderIds(hConnection, &folderList) ; 
if( ret != MSG_SUCCESS ) 
{ 
return MSG_ERR_USER_DEFINED; 
} 
if (folderList.iCount > 0) 
account .rootFolderld = folderList.folderIds[0]; 
else 
{ 
return MSG_ERR_USER_DEFINED; 
} 
MsgReleaseFolderIdList (&folderList) ; 
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//account extended data 
MSG_ACCOUNT_SMS_EXTDATA_S extData; 


extData. 
extData. 
extData. 
extData. 
extData. 
account. 


smsServerCenter.pString = "test.motorola. 
smsServerCenter.length = 17; 

portNumber = ; 
needDeliveryReport = 
autoReply = false; 
pExtData = &extData; 


true; 


//Call mapi method to create account 


ret = 


MsgAddAccount (hConnection, 


gaccount); 


return ret; 


com"; 
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7.12 Account Storage: Updating an Account 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
Initializing storage example. 


The code below updates a specific account. The function must have a valid account id for the operation. 
There is one required parameter: 


e hConnnection represents a client-server connection. 


MSG_ERROR_T UpdateAccount (MSG_CONNECTION_HANDLE_T hConnection, MSG_ACCOUNT_ID_T account_id) 


{ 


MSG_ERROR_T ret; 
_MSG_ACCOUNT_S account; 
_MSG_ACCOUNT_S x» ppAccount_original; 


//connection handle 
if( hConnection == NULL ) 
return MSG_ERR_USER_DEFINED; 


account .accountld= account_id; 


//get original account information 

MsgGetAccount (hConnection, account_id, ppAccount_original); 
//account name 

account .accountName .encodeType = MSG_ENCODE_ASCII; 


account .accountName.pString = "UpdateName"; 

account .accountName.length = 10; 

//message type 

account .msgType.mainType = ( * ppAccount_original)->msgType.mainType; 
account .msgType.subType = ( * ppAccount_original)->msgType.subType; 


//storage id 
account .storageld = ( * ppAccount_original)->storageld; 
account .defaultMsgStorageld = ( * ppAccount_original)->defaultMsgStorageld; 


//account root folder list 
account .rootFolderld = ( * ppAccount_original)->rootFolderld; 


//account extended data 

MSG_ACCOUNT_SMS_EXTDATA_S exData; 
exData.smsServerCenter.pString = "test2.motorola.com"; 
exData.smsServerCenter.length = 18; 

exData.portNumber = ; 

exData.needDeliveryReport = true; 

exData.autoReply = true; 

account.pExtData = &exData; 


//Call mapi method to update account 
ret = MsgUpdateAccount (hConnection, &account) ; 


return ret; 


} 
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7.13 Account Storage: Getting a Default Account 


Pre-condition: The storage has to be properly setup and initialized. To setup a storage, please refer to the 
Initializing storage example. 


The code below gets the default account id of a SMS account. 


MSG_ERROR_T GetDefaultAccount (MSG_CONNECTION_HANDLE_T hConnection) 
{ 
MSG_ERROR_T ret; 


//connection handle 
if( hConnection == NULL ) 
return MSG_ERR_USER_DEFINED; 


//get the default account id 
MSG_MESSAGE_TYPE_S msgType; 
msgType.mainType = MSG_MESSAGE_TYPE_SMS; 
msgType.subType = MSG_TYPE_SMS_TEXT; 


MSG_ACCOUNT_ID_T accountld; 
ret = MsgGetDefaultAccountID(hConnection, msgType, &accountId) ; 
if( ret != MSG_SUCCESS ) 
{ 
return MSG_ERR_USER_DEFINED; 


//here we can get detail information of the default account 
_MSG_ACCOUNT_S x*x*ppAccount; 
ret = MsgGetAccount (hConnection, accountId, ppAccount); 
if( ret != MSG_SUCCESS ) 
{ 
MsgReleaseAccount ( * ppAccount); 
return MSG_ERR_USER_DEFINED; 


// we can do something here for the default account 
//destroy object and free allocated memory 


MsgReleaseAccount( * ppAccount) ; 


return ret; 
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7.14 Sequence Charts for the LiMo Messaging API 


The following sequence charts are provided: 


Messaging Framework Startup 


Session: Sending a Message 


Session: Receiving Messages 


Message Storage: Creating and Opening Storage Connection 


Message Storage: Closing and Destroying Storage Connection 


Message Storage: Creating and Storing a Message 


Message Storage: Querying Messages 


Folder Storage: Creating and Storing a Folder 


Account Storage: Creating and Storing an Account 


Filter Plug-in: Set Filter List to Filter Messages 


Sending Messages (Normal Flow) 


Sending Messages (Alternative Flow) 


Receiving Messages 


Explore Message List (Flow for Listing Messages) 


Explore Message List (Flow for Browsing a Message) 


Explore Message List (Flow for Removal of a Message) 


Explore Message List (Flow for Moving Messages Between Folders) 


Manage Account and Profile (Flow for Creation of an Account) 


Manage Account and Profile (Flow for Update of an Account) 


Manage Account and Profile (Setting Default Account) 


Manage Account and Profile (Flow for Removing an Account) 


Manage Account and Profile (Alternative Flow for Removing an Account) 


Legend 


The chart below shows the legends used in the sequence charts. 


signal /message 


function call 


function return 


callback 


Figure 7.1: Sequence Chart Legend 
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Terms 


MAPI: Messaging API 

MsgFw: Messaging Framework 
TransportHandlerPlg: Transport Handler Plug-in 
FwStoPlg: Framework Storage Plug-in 
MsgStoPlg: Message Storage Plug-in 

FilterPlg: Filter plug-in 
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7.15 Messaging Framework Startup 


Precondition: Plug-in configuration file and Storage registry configuration file are ready. Data on all stor- 
ages are ready. 


MsgFw TransportHandlerPlg FilterPlg FwStoPlg MsgStoPlg 
Parse the plugin alls file to get all plugins’ informatio 


dlopen plugin library 


MsgPlsTransCreateHand]ec) 


Listen request from MAPI 


Figure 7.2: Messaging Framework Startup 
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7.16 Session: Sending a Message 


Application MAPI MsgFw TransportHandlerPlg 
MsgCreateSession() 


MssConnectSession() 


Connect to framework 


Get correct transport handler plugin 


MssPleTransSubmitRequest ¢ 


Status changed 


MNssPleTransOnStatusChanged¢ 


a mack’ } 


Figure 7.3: Session: Sending a Message 
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7.17 Session: Receiving Messages 


Application MAPI MsgFw FilterPlg TransportHandlerPlg 
MsgCreateSessiont 


MssConnectSession 


Msg 


work 


Set priorit 


Message received 


sIncoming¢) 


If matched, invoke callback function 


a 


Figure 7.4: Session: Receiving Messages 
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7.18 Message Storage: Creating and Opening Storage Connection 


Application MAPI MsgFw 
MsgCreateStoConnectionć) 


MsesOpenStoConnectiont) 


Connect to framework 


Figure 7.5: Message Storage: Creating and Opening Storage Connection 
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7.19 Message Storage: Closing and Destroying Storage Connection 


Application MAPI MsgFw 
MssCloseStoConnection() 


Disconnect with framework 


MssDestroyStoConnectiont) 


Figure 7.6: Message Storage: Closing and Destroying Storage Connection 
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7.20 Message Storage: Creating and Storing A Message 


Precondition: Storage connection is created and connected with messaging framework. 


Application MAPI MsgFw FwStoPlg MsgStoPlg 
Set message value 


MsgâddMessageć) 


Invoke framework to add 
poe unique message id 


Get correct message storage plugin 


MsgPleStoAddMessage() 


Figure 7.7: Message Storage: Creating and Storing a Message 
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7.21 Message Storage: Querying Messages 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FwStoPls MsgStoPl¢ 


For each message id, MsgGetMessage ) 


Invoke framework to get 
Get correct message storage plugin 


MssPleStoGetMessage() 


Figure 7.8: Message Storage: Querying Messages 
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7.22 Folder Storage: Creating and Storing a Folder 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FuStoPlg 
Create and fill folder 


MssAddFolder() 


Invoke framework to add f 


enerate unique folder id 


MssFuwStoAddFolder (> 


Figure 7.9: Messaging Framework Startup 
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7.23 Account Storage: Creating and Storing an Account 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FwStoPlg MsgStoPlg 
Create and fill account 


MssAddAccount () 


Invoke framework to add 
eae unique account id 
Get correct message storage plugin 


MsgPlgStoAddAccount() 


FwStoAddAccount ¢) 


Figure 7.10: Account Storage: Creating and Storing an Account 
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7.24 Filter Plug-in: Set Filter List to Filter Messages 


Application MAPI Framework filterPlugin 
MsgSetFilterList© 


send the filter list to framework 


sits the filter list and ee it to the session. 
get the session list when message are and check them one by one, sessions sorted by priority f 
get the filter list from session 


get each filter plugin capability, kii correct plugin for the filter id. 


aiaiai eds Check if the da satisfy the =a ‘uta rule. 
ita ae a RENEÓ If ME satisfies the filter rule, send the message to this sessi 


IF idad true, framwork stops TEN other low Ro session.. 


| 


Figure 7.11: Filter Plug-in: Set Filter List to Filter Messages 
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7.25 Sending Messages (Normal Flow) 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FwStoPlg MsgStoPlg TransportHandlerPl 
Create and fill MSG_MESSAGE_S struct 


NsgAddMessage¢ 
Invoke framework to add message 


Generate unique message id 


Get correct aii ii storage plugi 


MssPleStoAddMessage() 


| a | 


MsgConnectSession(> 


acre a 


MsgSubmitReq¢(MSG_REQUEST_TYPE_SEND) 
Send, Request to framework 


Get correct ia ind plugin 


MssP]sTransSubmitRequest( 
Status changed 
MssSPle edí) 


Invoke callback function 


iii a E 


Figure 7.12: Sending Messages (Normal Flow) 
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7.26 Sending Messages (Alternative Flow) 


Application MAPI MsgFw FwStoPlg MsgStoPlg TransportHandlerP1l 


| re | 


Create and fill MSG_MESSAGE_S struct 


MsgSubmitRegq(MSG_REQUEST_TYPE_SENDSAWVE) 


Send, Request to framework 


Generate unique message id 


Get correct aii storage plugi 


MssPleStoAddMessage() 


Get correct aie id plugin 
MsgP]eTransSubmitRequest ©) 
Encode dl ack and transmit 
en changed :Sent 
Ms: 


Invoke callback function 


A ESSE AO 


Figure 7.13: Sending Messages (Alternative Flow) 
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7.27 Receiving Messages 
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Figure 7.14: Receiving Messages 
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7.28 Explore Message List (Flow for Listing Messages) 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FwStoPlg MsgStoPlg 
MsgGetAccount¢) 


Invoke framework to get 
Get correct message storage plugin 


MssSP1g$StoGetAccount (> 


Get subfolders under Account rootFolderld, siani ime 


Invoke framework to get subfolders 


Create and fill MSG_QUERY_LIST_S 


1 


For each folder, query all m 


ages, a de ) 


Invoke framework to query messages 


| a ) 


Figure 7.15: Explore Message List (Flow for Listing Messages) 
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Figure 7.16: Explore Message List (Flow for Browsing a Message) 
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7.30 Explore Message List (Flow for Removal of a Message) 
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Figure 7.17: Explore Message List (Flow for Removal of a Message) 
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Figure 7.18: Explore Message List (Flow for Moving Messages Between Folders) 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


176 Page Documentation 


7.32 Manage Account and Profile (Flow for Creation of an Account) 


Precondition: Storage connection is created and connected with messaging framework 


Application MAPI MsgFw FwStoP1s MsgStoPl¢ 


Invoke framework to create 


call MsgFwStoAddFolder() multi times create root folder 


MsgAddAccount¢) 


Invoke framework to add 
ed unique account id 


Get correct message storage plugin 


MsgPl¢StoAddAccount() 


¡taa ¢ j 


Figure 7.19: Manage Account and Profile (Flow for Creation of an Account) 
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7.33 Manage Account and Profile (Flow for Update of an Account) 
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Figure 7.20: Manage Account and Profile (Flow for Update of an Account) 
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7.34 Manage Account and Profile (Setting Default Account) 


Precondition: Storage connection is created and connected with messaging framework 
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Figure 7.21: Manage Account and Profile (Setting Default Account) 
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7.35 Manage Account and Profile (Flow for Removing an Account) 
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Figure 7.22: Manage Account and Profile (Flow for Removing an Account) 
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7.36 Manage Account and Profile (Alternative Flow for Removing 
an Account) 
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Figure 7.23: Manage Account and Profile (Alternative Flow for Removing an Account) 
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